utils/gatelock/gatelock/_escape.py

# Copyright (c) 2026 Krzysztof Rudnicki
"""A sanctioned, rate-limited way out of a lock.

A hard lock without an escape hatch is a trap. screen-locker learned this and
grew "sick mode": you cannot always do the workout, so there is a bounded,
justified, tamper-evident way to say so. diet-guard's exit is cheap by nature
(log a meal). wake-alarm had neither -- its only exit was solving four
challenges in a row, which is a poor thing to require of someone who has just
woken up, and no exit at all if the alarm misfires at the wrong hour.

This module is the generic core of that hatch, so every app gets the *same*
mechanism instead of a copy that drifts:

* **Rolling budgets.** Once any window is exhausted the hatch disappears
  entirely -- it is not a slider, it is a hard stop.
* **Escalating lockout.** Each recent use doubles the wait, so the hatch gets
  progressively less convenient than just doing the thing.
* **A written justification.** Long enough to be inconvenient to invent, shown
  back to you next time so recycled excuses are visible.
* **Tamper evidence.** Every entry is HMAC-signed with a root-owned key, so
  hand-editing the history is detectable.

App-specific policy stays with the app: screen-locker's commitment penalty and
workout debt are not general, and are deliberately not modelled here.
"""

from __future__ import annotations

from datetime import timedelta
import json
import logging
from typing import TYPE_CHECKING, Any

from gatelock._escape_types import (
    EscapeDraft,
    EscapeHistory,
    EscapePolicy,
    _parse_iso,
    _today_iso,
)
from gatelock.log_integrity import compute_entry_hmac, verify_entry_hmac

if TYPE_CHECKING:
    from pathlib import Path

_logger = logging.getLogger(__name__)

# Re-exported after the 250-line split; gatelock's __init__ and the tests
# both import these from here.
__all__ = [
    "EscapeDraft",
    "EscapeHistory",
    "EscapePolicy",
    "EscapeTracker",
]


# The severity scale the dialog presents.
_MIN_SEVERITY = 1
_MAX_SEVERITY = 10


class EscapeTracker:
    """Budget, lockout and tamper-evident history for one app's hatch."""

    def __init__(
        self,
        policy: EscapePolicy,
        path: Path,
        *,
        key_file: Path | None = None,
    ) -> None:
        """Bind a policy to the file its history lives in."""
        self._policy = policy
        self._path = path
        self._key_file = key_file
        self.history = EscapeHistory()
        self.tampered = 0
        """How many loaded entries failed their integrity check."""

    @property
    def policy(self) -> EscapePolicy:
        """The policy this tracker enforces."""
        return self._policy

    def load(self) -> EscapeHistory:
        """Read history from disk, tolerating a missing or corrupt file.

        **Integrity problems never reduce recorded usage.** An entry that
        fails its HMAC check is kept for budget counting and reported loudly,
        rather than dropped. Dropping would be the intuitive move and is
        exactly wrong: ``verify_entry_hmac`` also returns False when the key
        file is merely *unreadable*, so "drop what you cannot verify" would
        turn a chmod on the key into an unlimited escape hatch. Tampering is
        something to shout about, not something that should widen the budget.
        """
        try:
            raw = json.loads(self._path.read_text(encoding="utf-8"))
        except FileNotFoundError:
            self.history = EscapeHistory()
            return self.history
        except (OSError, json.JSONDecodeError) as exc:
            _logger.warning("could not read escape history %s: %s", self._path, exc)
            self.history = EscapeHistory()
            return self.history
        if not isinstance(raw, dict):
            self.history = EscapeHistory()
            return self.history
        justifications = [
            entry for entry in raw.get("justifications", []) if isinstance(entry, dict)
        ]
        self.tampered = sum(1 for entry in justifications if not self._verified(entry))
        self.history = EscapeHistory(
            used_days=[d for d in raw.get("used_days", []) if isinstance(d, str)],
            justifications=justifications,
        )
        return self.history

    def _verified(self, entry: dict[str, Any]) -> bool:
        """Whether an entry's HMAC still matches its contents.

        A failure is reported, never acted on by discarding the entry -- see
        :meth:`load`.
        """
        if verify_entry_hmac(entry, key_file=self._key_file):
            return True
        _logger.error(
            "escape history entry dated %r failed its HMAC check -- the file "
            "has been edited outside the app, or the signing key is "
            "unreadable. The entry still counts against the budget.",
            entry.get("date", "?"),
        )
        return False

    def save(self) -> bool:
        """Write history back to disk. False if it could not be written."""
        payload = {
            "used_days": self.history.used_days,
            "justifications": self.history.justifications,
        }
        try:
            self._path.parent.mkdir(parents=True, exist_ok=True)
            self._path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
        except OSError:
            _logger.exception("could not save escape history %s", self._path)
            return False
        return True

    def count_in_window(self, days: int, *, today: str | None = None) -> int:
        """How many uses fall in the trailing ``days`` window."""
        today_str = today or _today_iso()
        today_dt = _parse_iso(today_str)
        if today_dt is None:
            return 0
        cutoff = today_dt - timedelta(days=days)
        count = 0
        for entry in self.history.used_days:
            parsed = _parse_iso(entry)
            if parsed is not None and cutoff < parsed <= today_dt:
                count += 1
        return count

    def is_budget_exhausted(self, *, today: str | None = None) -> bool:
        """Whether any rolling window has reached its limit.

        When True the app must not offer the hatch at all -- not offer it
        greyed out, not offer it with a longer wait. Gone.
        """
        policy = self._policy
        return (
            self.count_in_window(7, today=today) >= policy.budget_per_7_days
            or self.count_in_window(30, today=today) >= policy.budget_per_30_days
            or self.count_in_window(90, today=today) >= policy.budget_per_90_days
        )

    def compute_lockout_seconds(self, *, today: str | None = None) -> int:
        """Escalating wait: ``base * multiplier ** uses_in_30_days``."""
        recent = self.count_in_window(30, today=today)
        multiplier: int = self._policy.lockout_multiplier_per_recent**recent
        return int(self._policy.lockout_seconds * multiplier)

    def budget_summary(self, *, today: str | None = None) -> str:
        """One-line summary of remaining budget, for the dialog."""
        policy = self._policy
        week = self.count_in_window(7, today=today)
        month = self.count_in_window(30, today=today)
        quarter = self.count_in_window(90, today=today)
        return (
            f"{policy.label}: {week}/{policy.budget_per_7_days}w · "
            f"{month}/{policy.budget_per_30_days}m · "
            f"{quarter}/{policy.budget_per_90_days}q"
        )

    def validate(self, draft: EscapeDraft) -> str | None:
        """Return a user-facing complaint about ``draft``, or None if valid."""
        if not draft.reason.strip():
            return "Say what the problem is."
        if not draft.onset.strip():
            return "Say when it started."
        if not _MIN_SEVERITY <= draft.severity <= _MAX_SEVERITY:
            return f"Severity must be between {_MIN_SEVERITY} and {_MAX_SEVERITY}."
        minimum = self._policy.justification_min_chars
        if len(draft.description.strip()) < minimum:
            written = len(draft.description.strip())
            return f"Explain properly: {written}/{minimum} characters."
        return None

    def record(self, draft: EscapeDraft, *, today: str | None = None) -> bool:
        """Sign and append a use of the hatch. False if it could not be saved."""
        today_str = today or _today_iso()
        entry: dict[str, Any] = {
            "date": today_str,
            "policy": self._policy.name,
            "reason": draft.reason.strip(),
            "onset": draft.onset.strip(),
            "severity": draft.severity,
            "description": draft.description.strip(),
        }
        signature = compute_entry_hmac(entry, key_file=self._key_file)
        if signature is not None:
            entry["hmac"] = signature
        self.history.justifications.append(entry)
        if today_str not in self.history.used_days:
            self.history.used_days.append(today_str)
        return self.save()

    def recent_justifications(self, count: int | None = None) -> list[dict[str, Any]]:
        """The most recent justifications, newest last."""
        limit = count if count is not None else self._policy.history_review_count
        return self.history.justifications[-limit:]

    def format_recent(self, count: int | None = None) -> str:
        """Render past justifications for read-back in the dialog.

        Showing these is half the deterrent: a recycled excuse is obvious when
        the last ten are on screen above the form.
        """
        entries = self.recent_justifications(count)
        if not entries:
            return "(no previous uses)"
        return "\n".join(
            f"{entry.get('date', '?')}  [{entry.get('severity', '?')}/10] "
            f"{entry.get('reason', '')}: {entry.get('description', '')[:120]}"
            for entry in entries
        )