freemyid 0.2.0.dev1__py3-none-any.whl

freemyid/cli_json.py

@@ -0,0 +1,198 @@
+"""Stable machine-readable output for the CLI (`--json`) and the documented exit codes.
+
+OWNER: automation-engineer (CLI v0.2). Reference: docs/CLI.md.
+
+Rules for every shape here:
+* each document is one JSON object with ``"schema": "<name>/1"``; fields are only ever
+  added, never renamed or removed, within a schema version;
+* no PII beyond what the human output already shows (profile labels, broker names, to-do
+  titles), never secrets, never copy-fields, letters, addresses or mailbox details;
+* timestamps are ISO 8601 UTC strings or null.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import date, datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .engine.runner import RunReport
+    from .models import BrokerStatus, Profile, Registry, Request, Todo
+
+# Exit codes (docs/CLI.md). Never reuse a number for something else.
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_NEEDS_HUMAN = 3
+EXIT_NOT_CONFIGURED = 4
+
+
+def _ts(d: datetime | date | None) -> str | None:
+    return d.isoformat() if d is not None else None
+
+
+def emit(doc: dict[str, Any]) -> None:
+    """Write one JSON document to stdout (plain print: rich would wrap long lines)."""
+    sys.stdout.write(json.dumps(doc, sort_keys=False, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def skipped_entry(p: Profile, reason: str) -> dict[str, Any]:
+    return {"profile_id": p.id, "label": p.label, "reason": reason}
+
+
+def status_doc(rows: list[tuple[Profile, list[BrokerStatus], int]], names: dict[str, str],
+               skipped: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "schema": "status/1",
+        "profiles": [{
+            "profile_id": p.id,
+            "label": p.label,
+            "open_todos": todos,
+            "brokers": [{
+                "broker_id": st.broker_id,
+                "broker_name": names.get(st.broker_id, st.broker_id),
+                "state": st.state.value,
+                "tier": st.tier.value if st.tier else None,
+                "updated_at": _ts(st.updated_at),
+                "last_scan_at": _ts(st.last_scan_at),
+                "last_submitted_at": _ts(st.last_submitted_at),
+                "next_check_at": _ts(st.next_check_at),
+                "attempts": st.attempts,
+                "escalation_level": st.escalation_level,
+            } for st in sorted(sts, key=lambda s: s.broker_id)],
+        } for p, sts, todos in rows],
+        "skipped": skipped,
+    }
+
+
+def profiles_doc(rows: list[tuple[Profile, bool]]) -> dict[str, Any]:
+    return {
+        "schema": "profiles/1",
+        "profiles": [{
+            "id": p.id,
+            "label": p.label,
+            "state_of_residence": p.state_of_residence,
+            "consent_basis": p.consent.basis.value,
+            "consent_ok": ok,
+            "has_mailbox": p.mailbox is not None,
+            "email_mode": p.email_mode.value,
+            "created_at": _ts(p.created_at),
+        } for p, ok in rows],
+    }
+
+
+def todos_doc(rows: list[tuple[Profile, Todo]], skipped: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "schema": "todos/1",
+        "todos": [{
+            "id": t.id,
+            "profile_id": p.id,
+            "label": p.label,
+            "broker_id": t.broker_id,
+            "kind": t.kind.value,
+            "title": t.title,
+            "request_id": t.request_id,
+            "created_at": _ts(t.created_at),
+        } for p, t in rows],
+        "skipped": skipped,
+    }
+
+
+def outbox_doc(reqs: list[Request]) -> dict[str, Any]:
+    return {
+        "schema": "outbox/1",
+        "requests": [{
+            "id": r.id,
+            "profile_id": r.profile_id,
+            "broker_id": r.broker_id,
+            "kind": r.kind.value,
+            "method": r.method.value,
+            "status": r.status.value,
+            "attempt": r.attempt,
+            "created_at": _ts(r.created_at),
+        } for r in reqs],
+    }
+
+
+def registry_doc(reg: Registry, source: str, warnings: list[str]) -> dict[str, Any]:
+    return {
+        "schema": "registry/1",
+        "version": reg.version,
+        "updated": _ts(reg.updated),
+        "source": source,
+        "warnings": list(warnings),
+        "brokers": [{
+            "id": b.id,
+            "name": b.name,
+            "url": str(b.url),
+            "category": b.category.value,
+            "method": b.method.value,
+            "verification_status": b.verification_status.value,
+            "has_captcha": b.has_captcha,
+            "covered_by": b.covered_by,
+            "priority": b.priority,
+            "enabled": b.enabled,
+        } for b in sorted(reg.brokers, key=lambda b: (-b.priority, b.id))],
+    }
+
+
+def registry_source_doc(reg: Registry, source: str, warnings: list[str]) -> dict[str, Any]:
+    return {"schema": "registry-source/1", "source": source, "version": reg.version,
+            "updated": _ts(reg.updated), "brokers": len(reg.brokers),
+            "warnings": list(warnings)}
+
+
+def schedule_doc(platform: str | None, detail: str) -> dict[str, Any]:
+    low = detail.lower()
+    installed = bool(detail) and "not installed" not in low and "not supported" not in low
+    return {"schema": "schedule/1", "platform": platform, "installed": installed,
+            "detail": detail}
+
+
+def reports_doc(rows: list[tuple[Profile, str, str]], skipped: list[dict[str, Any]]
+                ) -> dict[str, Any]:
+    return {"schema": "reports/1",
+            "reports": [{"profile_id": p.id, "label": p.label, "format": fmt, "path": path}
+                        for p, fmt, path in rows],
+            "skipped": skipped}
+
+
+def run_doc(rep: RunReport, *, scan_only: bool, headless: bool, exit_code: int,
+            skipped: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "schema": "run/1",
+        "dry_run": rep.dry_run,
+        "scan_only": scan_only,
+        "headless": headless,
+        "exit_code": exit_code,
+        "profiles": [{
+            "profile_id": pid,
+            "label": rep.labels.get(pid, pid[:8]),
+            "states": {k.value: v for k, v in sorted(counts.items(), key=lambda kv: kv[0].value)},
+            "tiers": {t.value: n for t, n in sorted(rep.tiers.get(pid, {}).items())},
+        } for pid, counts in rep.per_profile.items()],
+        "needs_human": rep.needs_human,
+        "errors": rep.errors,
+        "skipped_not_due": rep.skipped_not_due,
+        "skipped_profiles": rep.skipped_profiles,
+        "submitted": rep.submitted,
+        "queued_emails": rep.queued_emails,
+        "drafted_emails": rep.drafted_emails,
+        "open_todos": rep.open_todos,
+        "skipped": skipped,
+        "summary": rep.summary_lines(),
+    }
+
+
+def secrets_doc(backend: str, configured: str | None, usable: bool,
+                keychain_available: bool) -> dict[str, Any]:
+    """Backend names only; never a key, passphrase, path contents or password."""
+    return {"schema": "secrets/1", "backend": backend, "configured": configured,
+            "usable": usable, "keychain_available": keychain_available}
+
+
+def failure_doc(code: int, reason: str) -> dict[str, Any]:
+    """What `run --headless --json` prints when it fails closed before running."""
+    return {"schema": "error/1", "exit_code": code, "reason": reason}

freemyid/config.py

@@ -0,0 +1,43 @@
+"""App config (non-PII) in FREEMYID_HOME/config.yaml. OWNER: orchestrator."""
+from __future__ import annotations
+
+import sys
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict
+
+from . import paths
+
+
+class Config(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    registry_url: str | None = None          # raw URL to registry.yaml in the user's GitHub repo
+    registry_sha256_url: str | None = None   # optional: URL of a .sha256 file to pin content
+    extra_allowed_hosts: list[str] = []      # e.g. playwright CDN if user approved download
+    browser_channel: str | None = "msedge" if sys.platform == "win32" else "chrome"
+    browser_automation: bool = True          # Automatic tier on/off (engine.tiers)
+    headless: bool = True
+    min_delay_s: float = 3.0
+    max_delay_s: float = 12.0
+    max_retries: int = 3
+    user_agent_suffix: str = "FreeMyID/0.1 (personal privacy opt-out tool)"
+    wizard_port: int = 8765
+    real_submissions_enabled: bool = False   # flipped only after explicit user approval
+    # Where the data key and mailbox passwords live (secret_backends). None = auto: OS
+    # keychain if usable, else passphrase. Change with `freemyid secrets migrate`.
+    secrets_backend: Literal["keyring", "passphrase", "systemd-creds"] | None = None
+
+
+def load() -> Config:
+    p = paths.config_path()
+    if p.exists():
+        return Config.model_validate(yaml.safe_load(p.read_text()) or {})
+    return Config()
+
+
+def save(cfg: Config) -> None:
+    p = paths.config_path()
+    p.write_text(yaml.safe_dump(cfg.model_dump(), sort_keys=False))
+    p.chmod(0o600)

freemyid/consent.py

@@ -0,0 +1,82 @@
+"""The one consent gate. The CLI, the runner and the wizard all import it.
+
+OWNER: orchestrator (written by peer session e8 for SEC-06).
+
+Rules (fail closed):
+* someone has to have typed their name to attest;
+* the consent text version must be one this build knows about;
+* a minor (``is_minor`` flag OR an age computed from dob/age under 18) needs
+  GUARDIAN_OF_MINOR;
+* an adult needs SELF or AUTHORIZED_AGENT (GUARDIAN_OF_MINOR is refused);
+* AUTHORIZED_AGENT needs ``authorization_doc`` to name stored consent evidence
+  for this same profile, and its encrypted file has to exist on disk.
+"""
+from __future__ import annotations
+
+from datetime import date
+from typing import TYPE_CHECKING
+
+from . import paths
+from .models import ConsentBasis, Profile
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .storage import Store
+
+#: Version id of the consent text the wizard currently shows.
+CURRENT_TEXT_VERSION = "2026-11-c"
+#: Every consent text version a stored profile may have accepted. Add (never remove)
+#: when the wording changes in a way that doesn't need everyone to consent again.
+ACCEPTED_TEXT_VERSIONS: frozenset[str] = frozenset({"2026-11-a", "2026-11-b", CURRENT_TEXT_VERSION})
+#: broker_id the wizard uses when it saves the signed authorization as evidence.
+CONSENT_EVIDENCE_BROKER = "_consent"
+
+ADULT_AGE = 18
+
+
+def is_minor(p: Profile, today: date | None = None) -> bool:
+    """True if the profile is flagged as a minor OR its estimated age is under 18."""
+    if p.is_minor:
+        return True
+    age = p.estimated_age(today)
+    return age is not None and age < ADULT_AGE
+
+
+def authorization_on_file(p: Profile, store: Store) -> bool:
+    """The signed authorization named in the consent is stored for this profile and on disk."""
+    doc = p.consent.authorization_doc
+    if not doc:
+        return False
+    for ev in store.list_evidence(p.id, CONSENT_EVIDENCE_BROKER):
+        if ev.id == doc and ev.profile_id == p.id:
+            return (paths.evidence_dir() / ev.relpath).is_file()
+    return False
+
+
+def consent_ok(p: Profile, store: Store | None = None, *,
+               today: date | None = None) -> tuple[bool, str]:
+    """Hard consent gate. Returns ``(ok, reason)``; reason is "" when ok.
+
+    Pass ``store`` so the authorized-agent document can be checked. Without a store an
+    AUTHORIZED_AGENT profile is refused (fail closed).
+    """
+    c = p.consent
+    if not c.attested_by.strip():
+        return False, "consent has no attesting name"
+    if c.text_version not in ACCEPTED_TEXT_VERSIONS:
+        return False, "consent was given to an older or unknown consent text; please re-confirm"
+    if is_minor(p, today):
+        if c.basis != ConsentBasis.GUARDIAN_OF_MINOR:
+            return False, "minor profile requires parent/guardian consent"
+        return True, ""
+    if c.basis == ConsentBasis.GUARDIAN_OF_MINOR:
+        return False, ("guardian consent only covers people under 18; this adult must "
+                       "consent themselves or sign an agent authorization")
+    if c.basis == ConsentBasis.AUTHORIZED_AGENT:
+        if not c.authorization_doc:
+            return False, "authorized agent needs the signed authorization attached"
+        if store is None or not authorization_on_file(p, store):
+            return False, "the signed authorization could not be found; please attach it again"
+        return True, ""
+    if c.basis == ConsentBasis.SELF:
+        return True, ""
+    return False, f"unknown consent basis {c.basis!r}"

freemyid/crypto.py

@@ -0,0 +1,197 @@
+"""At-rest encryption. Key lives in the OS keychain or a passphrase wrap. OWNER: orchestrator.
+
+Where the key lives is decided by `secret_backends` (keyring | passphrase | systemd-creds).
+
+Field/blob-level AES-256-GCM. Ciphertext format: b"V1" + 12-byte nonce + ct||tag.
+SQLCipher was considered; blob encryption avoids cross-platform native packaging issues.
+Only ids, enums and timestamps are stored in clear; all PII is inside encrypted blobs.
+
+Evidence files are bound (AAD) to their path relative to FREEMYID_HOME/evidence, so a file
+cannot be swapped between profiles/brokers. Store a `key_check()` value in the DB `meta`
+table on first use and `verify_key_check()` it on open to detect a wrong/lost key early.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+import os
+import sys
+from pathlib import Path
+
+import keyring
+import keyring.errors
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from . import paths
+
+SERVICE = "freemyid"
+KEY_NAME = "db-key-v1"
+_MAGIC = b"V1"
+_KEY_CHECK_PLAINTEXT = b"freemyid-key-check-v1"
+_KEY_CHECK_AAD = b"meta:key_check"
+_FILE_AAD_PREFIX = b"evidence:"
+
+log = logging.getLogger(__name__)
+
+# Backends that would silently lose the key or store it in clear text.
+_REJECTED_BACKENDS = {
+    "keyring.backends.fail.Keyring",
+    "keyring.backends.null.Keyring",
+    "keyrings.alt.file.PlaintextKeyring",
+}
+
+
+class KeyUnavailable(RuntimeError):
+    """OS keychain locked/unavailable (e.g. headless session). Surface as NEEDS_HUMAN."""
+
+
+def _test_key() -> bytes | None:
+    """FREEMYID_TEST_KEY is honored only under pytest or with FREEMYID_ALLOW_TEST_KEY=1.
+
+    The test key is a SHA-256 of an env string (no KDF): never acceptable for real data.
+    A leftover variable outside tests is refused loudly rather than silently ignored, so
+    data is never split between two keys.
+    """
+    test_key = os.environ.get("FREEMYID_TEST_KEY")
+    if not test_key:
+        return None
+    if "pytest" in sys.modules or os.environ.get("FREEMYID_ALLOW_TEST_KEY") == "1":
+        log.warning("Using FREEMYID_TEST_KEY: weak test-only key, never use with real data")
+        return hashlib.sha256(test_key.encode()).digest()
+    raise KeyUnavailable(
+        "FREEMYID_TEST_KEY is set outside the test suite; unset it to use the OS keychain"
+    )
+
+
+def _backend_names(kr: object) -> list[str]:
+    backends = getattr(kr, "backends", None)  # ChainerBackend
+    objs = list(backends) if backends else [kr]
+    return [f"{type(b).__module__}.{type(b).__qualname__}" for b in objs]
+
+
+def _check_backend() -> None:
+    names = _backend_names(keyring.get_keyring())
+    bad = [n for n in names if n in _REJECTED_BACKENDS]
+    if bad and len(bad) == len(names):
+        raise KeyUnavailable(f"no secure OS keychain available (backend: {', '.join(bad)})")
+
+
+def _decode_key(stored: str) -> bytes:
+    try:
+        key = base64.b64decode(stored, validate=True)
+    except ValueError as e:
+        raise KeyUnavailable("stored key is corrupt") from e
+    if len(key) != 32:
+        raise KeyUnavailable("stored key has the wrong length")
+    return key
+
+
+def _get_or_create_key() -> bytes:
+    """Test key (pytest only), else the selected secrets backend (secret_backends.select)."""
+    if (tk := _test_key()) is not None:
+        return tk
+    from . import secret_backends
+    return secret_backends.select().load_data_key()
+
+
+def _keyring_get_or_create_key() -> bytes:
+    """The OS keychain path (default backend; unchanged since 0.1)."""
+    try:
+        _check_backend()
+        stored = keyring.get_password(SERVICE, KEY_NAME)
+        if stored is None:
+            key = AESGCM.generate_key(bit_length=256)
+            keyring.set_password(SERVICE, KEY_NAME, base64.b64encode(key).decode())
+            # Re-read: if another process won a first-run race, use its key, not ours.
+            stored = keyring.get_password(SERVICE, KEY_NAME)
+            if stored is None:
+                raise KeyUnavailable("keychain did not persist the key")
+        return _decode_key(stored)
+    except keyring.errors.KeyringError as e:
+        raise KeyUnavailable(str(e)) from e
+
+
+def delete_key() -> None:
+    """Remove the data key from every backend (used by `freemyid wipe`): the OS keychain
+    entry and the passphrase-wrapped key file. Missing key or no keychain at all is fine."""
+    from . import secret_backends
+    secret_backends.KeyringBackend().delete_data_key()
+    secret_backends.PassphraseBackend().delete_data_key()
+
+
+class Cipher:
+    def __init__(self, key: bytes | None = None) -> None:
+        if key is None:
+            key = _get_or_create_key()
+        elif len(key) != 32:
+            raise ValueError("Cipher key must be 32 bytes (AES-256)")
+        self._aes = AESGCM(key)
+
+    def encrypt(self, data: bytes, aad: bytes = b"") -> bytes:
+        nonce = os.urandom(12)
+        return _MAGIC + nonce + self._aes.encrypt(nonce, data, aad or None)
+
+    def decrypt(self, blob: bytes, aad: bytes = b"") -> bytes:
+        if blob[:2] != _MAGIC:
+            raise ValueError("unknown ciphertext format")
+        return self._aes.decrypt(blob[2:14], blob[14:], aad or None)
+
+    # --- key check (store in DB meta to detect a wrong key before touching data) ---------
+
+    def key_check(self) -> str:
+        """Encrypted constant, base64 text, for storing in `meta`."""
+        return base64.b64encode(self.encrypt(_KEY_CHECK_PLAINTEXT, _KEY_CHECK_AAD)).decode()
+
+    def verify_key_check(self, value: str) -> bool:
+        try:
+            pt = self.decrypt(base64.b64decode(value), _KEY_CHECK_AAD)
+        except (InvalidTag, ValueError):
+            return False
+        return pt == _KEY_CHECK_PLAINTEXT
+
+    # --- files ----------------------------------------------------------------------------
+
+    @staticmethod
+    def _file_aad(path: Path) -> bytes:
+        """AAD = path relative to FREEMYID_HOME/evidence (POSIX form), so it survives moving
+        FREEMYID_HOME. Files outside the evidence dir are bound to their absolute path."""
+        p = Path(os.path.abspath(path))
+        base = Path(os.path.abspath(paths.home() / "evidence"))
+        try:
+            rel = p.relative_to(base).as_posix()
+        except ValueError:
+            rel = p.as_posix()
+        return _FILE_AAD_PREFIX + rel.encode()
+
+    def encrypt_file(self, src_bytes: bytes, dest: Path) -> str:
+        """Write encrypted file; return sha256 of the plaintext."""
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(self.encrypt(src_bytes, aad=self._file_aad(dest)))
+        dest.chmod(0o600)
+        return hashlib.sha256(src_bytes).hexdigest()
+
+    def decrypt_file(self, path: Path) -> bytes:
+        return self.decrypt(path.read_bytes(), aad=self._file_aad(path))
+
+
+# --- passphrase-based export (family installer pre-filled profiles) --------------------------
+
+def export_with_passphrase(data: bytes, passphrase: str) -> bytes:
+    from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+
+    salt = os.urandom(16)
+    key = Scrypt(salt=salt, length=32, n=2**15, r=8, p=1).derive(passphrase.encode())
+    nonce = os.urandom(12)
+    return b"VP1" + salt + nonce + AESGCM(key).encrypt(nonce, data, b"freemyid-profile")
+
+
+def import_with_passphrase(blob: bytes, passphrase: str) -> bytes:
+    from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+
+    if blob[:3] != b"VP1":
+        raise ValueError("not a Free My ID profile file")
+    salt, nonce, ct = blob[3:19], blob[19:31], blob[31:]
+    key = Scrypt(salt=salt, length=32, n=2**15, r=8, p=1).derive(passphrase.encode())
+    return AESGCM(key).decrypt(nonce, ct, b"freemyid-profile")