privacyfence 4.0.0__py3-none-any.whl

privacyfence/__init__.py

@@ -0,0 +1,17 @@
+"""PrivacyFence: privacy proxy between Claude (MCP) and your personal data, with an embedded web
+approval/settings UI."""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("privacyfence")
+except PackageNotFoundError:
+    # Not installed with metadata at all -- e.g. run straight out of a
+    # source checkout without `pip install -e .`/`pip install .` first, or a
+    # frozen build missing --copy-metadata (see scripts/build_dmg.sh). Never
+    # crash the whole package over a display string: fall back to the same
+    # placeholder [tool.setuptools_scm]'s fallback_version in pyproject.toml
+    # uses for "no tag reachable yet", so update_checker.py's parse_version()
+    # still accepts it (and correctly never claims it's up to date).
+    __version__ = "0.0.0.dev0"

privacyfence/app_credentials.py

@@ -0,0 +1,30 @@
+"""PrivacyFence application-level credentials.
+
+Telegram's api_id/api_hash identify the PrivacyFence *application* to
+Telegram's API (MTProto has no concept of "organization" the way OAuth
+does) — they are the same for every user and every phone number, and are
+not a substitute for per-user auth (still phone + code + optional 2FA, see
+menu_bar.py). Because this repo is public, the real values are never
+committed: release builds bake them in from CI secrets (see
+scripts/build_dmg.sh) into the git-ignored ``_telegram_credentials`` module
+generated right before packaging. Local/dev builds fall back to the
+PRIVACYFENCE_TELEGRAM_API_ID / PRIVACYFENCE_TELEGRAM_API_HASH env vars.
+"""
+from __future__ import annotations
+
+import os
+
+
+def telegram_app_credentials() -> tuple[int, str] | None:
+    try:
+        from . import _telegram_credentials  # generated at build time; git-ignored
+    except ImportError:
+        pass
+    else:
+        return int(_telegram_credentials.API_ID), _telegram_credentials.API_HASH
+
+    api_id = os.environ.get("PRIVACYFENCE_TELEGRAM_API_ID")
+    api_hash = os.environ.get("PRIVACYFENCE_TELEGRAM_API_HASH")
+    if api_id and api_hash:
+        return int(api_id), api_hash
+    return None

privacyfence/approval_icons.py

@@ -0,0 +1,58 @@
+"""Shared icon-asset loading for approval surfaces.
+
+Locates the bundled shield/connector PNGs (resources/icon_*.png,
+resources/connector_icons/<name>.png) and returns them as base64 data URIs
+for embedding directly into a card-stack HTML document -- see
+approval_window_html.py's module docstring for why that document must never
+trigger a network fetch to render.
+
+Plain filesystem + base64, no AppKit/PyObjC dependency -- both
+approval_window.py's native host (AppKit/WKWebView) and web_approval_ui.py's
+browser host need the exact same data URIs, so this is factored out here
+rather than duplicated, and importable on any platform. approval_window.py
+keeps its own private _icon_path/_connector_icon_path/_icon_data_uri (not
+migrated onto this module) so this change stays scoped to the new web
+surface without touching the native path's own, separately-tested code.
+"""
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+_RESOURCES = Path(__file__).parent / "resources"
+
+_icon_data_uri_cache: dict[str, str] = {}
+
+
+def shield_icon_path() -> str | None:
+    """PrivacyFence's own shield mark, top-right of every card -- see
+    approval_window_html.py's _header_html. Same silent-skip fallback as
+    connector_icon_path(): no bundled asset just means no icon, never an
+    error."""
+    for name in ("icon_64.png", "icon_512.png", "icon_32.png"):
+        p = _RESOURCES / name
+        if p.exists():
+            return str(p)
+    return None
+
+
+def connector_icon_path(connector: str) -> str | None:
+    """Real per-service brand icon (Gmail/Drive/Slack/etc.), top-left,
+    alongside the "PrivacyFence" kicker -- see resources/connector_icons/README
+    for where the bundled assets come from."""
+    if not connector:
+        return None
+    p = _RESOURCES / "connector_icons" / f"{connector}.png"
+    return str(p) if p.exists() else None
+
+
+def icon_data_uri(path: str | None) -> str:
+    """Base64 data: URI for a vendored PNG icon, or "" if missing. Cached
+    (these are a fixed, small set of bundled resources, not user data) so
+    repeated approvals don't re-read/re-encode the same file."""
+    if not path:
+        return ""
+    if path not in _icon_data_uri_cache:
+        data = base64.b64encode(Path(path).read_bytes()).decode("ascii")
+        _icon_data_uri_cache[path] = f"data:image/png;base64,{data}"
+    return _icon_data_uri_cache[path]

privacyfence/approval_list_html.py

@@ -0,0 +1,285 @@
+"""Pure-function HTML for the ``/approvals`` list page
+(docs/approval-list-ui-ux.md §2, the P1-compatible slice its own §6 says
+can land ahead of P3's full design -- the row shape, the empty state, and
+the central asymmetry of §2.2: **Deny is on the row; Allow is never on the
+row.** Denying without reading the card cannot leak anything; approving
+from a one-line summary is exactly the habituation failure the card exists
+to prevent, so there is no "Allow" button here at all -- only "Review",
+which opens the real card.
+
+``build_list_html(rows)`` is the first paint (web/routes_approvals.py, given
+``approvals.PendingApproval`` objects, each with a real connector icon --
+see ``row_from_approval`` below); ``window.__pfRenderApprovals(state)`` is
+the live re-render web_shell.py's SSE dispatch calls with
+web/state_stream.py's own "approvals" event payload
+(``PendingApproval.to_summary_dict()``, which carries no icon -- building
+one needs approval_icons.py, a filesystem read this module deliberately
+doesn't do on every SSE tick). A live-updated row therefore renders with a
+plain connector-initial badge instead of the real icon; a decided row
+leaves the list within one poll interval regardless (web/state_stream.py's
+``_APPROVALS_POLL_SECONDS``), so the visual gap is real but short-lived --
+a documented simplification of this phase's own P1-compatible scope, not
+an oversight.
+"""
+from __future__ import annotations
+
+import json
+import secrets
+from datetime import datetime, timezone
+from html import escape as _html_escape
+from typing import Any
+
+from . import approval_icons
+
+_EMPTY_STATE = (
+    '<div class="pf-approvals-empty">'
+    '<div class="pf-approvals-empty-title">Nothing is waiting.</div>'
+    '<div class="pf-approvals-empty-sub">PrivacyFence is watching.</div>'
+    "</div>"
+)
+
+_CSS = """
+.pf-approvals-page { max-width: 720px; margin: 0 auto; padding: 24px 20px 60px; width: 100%; }
+.pf-approvals-heading { font-size: 13px; color: var(--color-neutral-600); margin-bottom: 14px; }
+.pf-approvals-empty {
+  text-align: center; padding: 80px 20px; color: var(--color-neutral-600);
+}
+.pf-approvals-empty-title { font-size: 16px; font-weight: 600; color: var(--color-text); margin-bottom: 4px; }
+.pf-approvals-empty-sub { font-size: 13px; }
+.pf-approval-row {
+  display: flex; align-items: center; gap: 14px; padding: 14px 16px;
+  background: var(--color-surface); border-radius: var(--radius-lg); margin-bottom: 10px;
+}
+.pf-approval-icon {
+  width: 28px; height: 28px; border-radius: var(--radius-md); flex-shrink: 0; object-fit: contain;
+  background: var(--color-neutral-200);
+}
+.pf-approval-icon-fallback {
+  display: flex; align-items: center; justify-content: center;
+  font-size: 12px; font-weight: 700; color: var(--color-neutral-600);
+}
+.pf-approval-main { flex: 1; min-width: 0; }
+.pf-approval-title {
+  font-size: 14px; font-weight: 600; color: var(--color-text);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.pf-approval-kicker { font-size: 12px; color: var(--color-neutral-600); margin-top: 2px; }
+.pf-approval-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
+.pf-btn-deny, .pf-btn-review {
+  font-size: 12.5px; font-weight: 600; padding: 7px 12px; border-radius: var(--radius-md);
+  border: none; cursor: pointer; text-decoration: none; white-space: nowrap;
+}
+.pf-btn-deny { background: transparent; color: var(--color-danger); border: 1px solid var(--color-divider); }
+.pf-btn-review { background: var(--color-accent); color: #fff; }
+"""
+
+# Runtime dispatch: sessionStorage's pending toast (left by the card page's
+# own shim right before it navigates back here -- see
+# web/routes_approvals.py's _bridge_shim), the empty-state/row re-render on
+# every "approvals" SSE event, and the row-level Deny button (a direct POST
+# to the decide endpoint, no navigation to the card at all -- §2.2's own
+# point: denying needs no context).
+_JS = """
+(function () {
+  function relAge(iso) {
+    if (!iso) return '';
+    var then = new Date(iso).getTime();
+    if (isNaN(then)) return '';
+    var s = Math.max(0, Math.floor((Date.now() - then) / 1000));
+    if (s < 60) return 'just now';
+    var m = Math.floor(s / 60);
+    if (m < 60) return m + 'm ago';
+    var h = Math.floor(m / 60);
+    if (h < 24) return h + 'h ago';
+    return Math.floor(h / 24) + 'd ago';
+  }
+
+  function esc(s) {
+    return String(s == null ? '' : s)
+      .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  }
+
+  function rowHtml(row) {
+    var title = esc(row.tool_name || row.summary || (row.kind === 'card' ? 'Approval' : 'Confirmation'));
+    var kicker = [row.connector ? row.connector.charAt(0).toUpperCase() + row.connector.slice(1) : '',
+      row.tool || '', relAge(row.created_at)].filter(Boolean).join(' · ');
+    var initial = (row.connector || '?').charAt(0).toUpperCase();
+    return '<div class="pf-approval-row" data-approval-id="' + esc(row.id) + '">' +
+      '<div class="pf-approval-icon pf-approval-icon-fallback">' + esc(initial) + '</div>' +
+      '<div class="pf-approval-main"><div class="pf-approval-title">' + title + '</div>' +
+      '<div class="pf-approval-kicker">' + esc(kicker) + '</div></div>' +
+      '<div class="pf-approval-actions">' +
+      '<button type="button" class="pf-btn-deny" data-deny="' + esc(row.id) + '">Deny</button>' +
+      '<a class="pf-btn-review" href="/approvals/' + esc(row.id) + '">Review →</a></div></div>';
+  }
+
+  function render(rows) {
+    var container = document.getElementById('pf-approvals-list');
+    if (!container) return;
+    if (!rows || !rows.length) {
+      container.innerHTML = %(empty)s;
+      return;
+    }
+    container.innerHTML = rows.map(rowHtml).join('');
+  }
+  window.__pfRenderApprovals = render;
+
+  function denyRow(id) {
+    fetch('/api/approvals/' + encodeURIComponent(id) + '/decide', {
+      method: 'POST', credentials: 'same-origin', headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({result: 'deny', csrf: %(csrf)s}),
+    }).then(function (r) {
+      var row = document.querySelector('[data-approval-id="' + id + '"]');
+      if (row) { row.remove(); }
+      // §4.4's "offer it after the first successful decision" isn't only
+      // the card page's own decision (whose own return-to-list flow
+      // triggers this same prompt via the DOMContentLoaded handler below)
+      // -- row-level Deny is a first-class decision path (§2.2's whole
+      // point: denying needs no card) and never goes through that flow at
+      // all, so without this, a workflow that only ever denies from the
+      // list would never trigger the notification permission pre-prompt.
+      if (r.ok && window.__pfNotifPrompt) { window.__pfNotifPrompt(); }
+    });
+  }
+
+  document.addEventListener('click', function (e) {
+    var btn = e.target.closest('[data-deny]');
+    if (btn) { denyRow(btn.getAttribute('data-deny')); }
+  });
+
+  // The card page's own return-to-list flow (web/routes_approvals.py's
+  // _bridge_shim) stashes a toast message here right before navigating
+  // back -- shown once, then cleared, so a page refresh never re-shows it.
+  // Deferred to DOMContentLoaded: #pf-shell-toast and window.__pfNotifPrompt
+  // are both defined by web_shell.py's own markup/script, which come
+  // *after* this <script> in document order (this module's body_html is
+  // wrapped inside <main>, ahead of the shell's own footer) -- running
+  // this inline, synchronously, would find neither yet.
+  document.addEventListener('DOMContentLoaded', function () {
+    try {
+      var raw = sessionStorage.getItem('pf_toast');
+      if (raw) {
+        sessionStorage.removeItem('pf_toast');
+        var toast = JSON.parse(raw);
+        var el = document.getElementById('pf-shell-toast');
+        if (el && toast && toast.msg) {
+          el.textContent = toast.msg;
+          el.classList.add('shown');
+          setTimeout(function () { el.classList.remove('shown'); }, 4000);
+        }
+        // §4.4: offer the notification permission pre-prompt right after
+        // the first successful decision, when the value is concrete --
+        // never on page load. window.__pfNotifPrompt (web_shell.py) itself
+        // no-ops past the first time (localStorage) and past a non-default
+        // permission state.
+        if (window.__pfNotifPrompt) { window.__pfNotifPrompt(); }
+      }
+    } catch (e) { /* sessionStorage unavailable -- toast just doesn't show */ }
+  });
+
+  // §3 point 4: focus moves to the next pending row's Review control, not
+  // into a re-opened card -- never auto-advance into a decision.
+  var firstReview = document.querySelector('.pf-btn-review');
+  if (firstReview) { firstReview.focus({preventScroll: true}); }
+})();
+"""
+
+
+def row_from_approval(card: Any) -> dict[str, Any]:
+    """``PendingApproval`` -> the same summary shape
+    ``PendingApproval.to_summary_dict()`` already produces (approvals.py) --
+    used for the server-rendered first paint here rather than calling that
+    method directly, only so this module stays the one place that decides
+    what a row needs to render (kept in sync with to_summary_dict() by the
+    field names below, not by importing it, since the two shapes need to
+    stay decoupled: an SSE payload field this module doesn't use yet
+    shouldn't have to be added here too)."""
+    return {
+        "id": card.id,
+        "kind": card.kind,
+        "connector": card.connector,
+        "tool": card.tool,
+        "tool_name": card.tool_name,
+        "summary": card.summary,
+        "created_at": _iso(card.created_at),
+    }
+
+
+def _iso(ts: float) -> str:
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()
+
+
+def _row_html(row: dict[str, Any]) -> str:
+    label = "Confirmation" if row.get("kind") != "card" else "Approval"
+    title = row.get("tool_name") or row.get("summary") or label
+    connector = (row.get("connector") or "").capitalize()
+    kicker = " · ".join(p for p in (connector, row.get("tool") or "", _relative_age(row.get("created_at", ""))) if p)
+    rid = row["id"]
+    icon_uri = approval_icons.icon_data_uri(approval_icons.connector_icon_path(row.get("connector", "")))
+    icon_html = (
+        f'<img class="pf-approval-icon" src="{_html_escape(icon_uri)}" alt="">' if icon_uri
+        else f'<div class="pf-approval-icon pf-approval-icon-fallback">{_html_escape(connector[:1])}</div>'
+    )
+    return (
+        f'<div class="pf-approval-row" data-approval-id="{_html_escape(rid)}">'
+        f"{icon_html}"
+        '<div class="pf-approval-main">'
+        f'<div class="pf-approval-title">{_html_escape(title)}</div>'
+        f'<div class="pf-approval-kicker">{_html_escape(kicker)}</div>'
+        "</div>"
+        '<div class="pf-approval-actions">'
+        f'<button type="button" class="pf-btn-deny" data-deny="{_html_escape(rid)}">Deny</button>'
+        f'<a class="pf-btn-review" href="/approvals/{_html_escape(rid)}">Review →</a>'
+        "</div>"
+        "</div>"
+    )
+
+
+def _relative_age(iso_ts: str) -> str:
+    if not iso_ts:
+        return ""
+    try:
+        dt = datetime.fromisoformat(iso_ts)
+    except ValueError:
+        return ""
+    seconds = max(0, int((datetime.now(timezone.utc) - dt).total_seconds()))
+    if seconds < 60:
+        return "just now"
+    minutes = seconds // 60
+    if minutes < 60:
+        return f"{minutes}m ago"
+    hours = minutes // 60
+    if hours < 24:
+        return f"{hours}h ago"
+    return f"{hours // 24}d ago"
+
+
+def build_list_html(rows: list[dict[str, Any]], *, csrf: str, nonce: str | None = None) -> str:
+    """The ``/approvals`` page body (dropped into web_shell.wrap's
+    ``<main>``) -- ``rows`` is a list of row_from_approval()'s shape,
+    newest first (same order approvals.PendingApprovalRegistry.
+    list_pending() already returns).
+
+    ``nonce``: the caller's current per-response CSP nonce (web/server.py's
+    ``_SecurityHeadersMiddleware``, via ``request.state.csp_nonce``) --
+    unlike approval_window_html.py's card documents, this fragment is
+    rendered fresh on every ``GET /approvals``, so it takes the request's
+    own nonce rather than minting one itself. Must be the same value
+    web_shell.wrap() is given for the rest of this same document, since
+    only one Content-Security-Policy header covers both. Defaults to a
+    fresh one when omitted (every caller outside this module's own tests
+    always passes the real per-request value explicitly)."""
+    nonce = nonce or secrets.token_urlsafe(18)
+    body = "".join(_row_html(r) for r in rows) if rows else _EMPTY_STATE
+    heading = (
+        f"{len(rows)} approval{'s' if len(rows) != 1 else ''} pending" if rows else ""
+    )
+    js = _JS % {"empty": json.dumps(_EMPTY_STATE), "csrf": json.dumps(csrf)}
+    return (
+        f'<style nonce="{nonce}">{_CSS}</style>'
+        '<div class="pf-approvals-page">'
+        + (f'<div class="pf-approvals-heading">{_html_escape(heading)}</div>' if heading else "")
+        + f'<div id="pf-approvals-list">{body}</div>'
+        "</div>"
+        f'<script nonce="{nonce}">{js}</script>'
+    )

privacyfence/approval_ui.py

@@ -0,0 +1,167 @@
+"""Approval UI seam: the interface gate.py depends on instead of importing
+a concrete approval-surface implementation directly.
+
+gate.py is the policy engine: auto-accept check -> block on a human decision
+-> audit log. The policy loop itself has no reason to know how a human
+decision actually gets shown -- it just needs something that can show the
+write-gate popup, the review-gate popup, and the two smaller confirmation
+dialogs, and return a decision. ApprovalUI is that something.
+
+Through P9 this had two implementations: NativeApprovalUI (macOS AppKit/
+WKWebView dialogs, via approval_popup.py) and WebApprovalUI (the same card
+stack, served over HTTP). P10 deleted the native one -- "two approval
+surfaces means two places for a security fix to land" -- leaving
+WebApprovalUI (web_approval_ui.py) as the sole implementation. The ABC
+stays here, and gate.py still reaches it through get_approval_ui() rather
+than importing WebApprovalUI directly, on purpose: that decision's own
+reasoning was "the ApprovalUI seam lets it come back if that proves
+wrong", so a future implementation (e.g. a Windows-native dialog for #121,
+once that's revisited) only needs to implement this interface and call
+init_approval_ui() with an
+instance of it -- gate.py's own call sites never change.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class ApprovalUI(ABC):
+    """One blocking human-approval surface. Every method mirrors one of
+    WebApprovalUI's own (see web_approval_ui.py), which in turn mirrors
+    approval_popup.py's pre-P10 free functions -- these signatures were kept
+    identical across that transition so nothing calling through this ABC had
+    to change shape.
+    """
+
+    @abstractmethod
+    def show_popup(
+        self,
+        title: str,
+        preview: dict[str, str],
+        details_text: str,
+        temp_accept_eligible: bool = False,
+        claude_reason: str = "",
+        write_content_flags: list[str] | None = None,
+        seen_count: int = 0,
+        connector: str = "",
+        accept_all_choices: list[tuple[str, str]] | None = None,
+        preview_bytes: bytes = b"",
+        preview_mime_type: str = "",
+        preview_tables: list[dict] | None = None,
+        preview_blocks: list[dict] | None = None,
+        table_only: bool = False,
+        upload_forced: bool = False,
+        layout: str = "narrow",
+    ) -> tuple[str, int | None]:
+        """Approval popup for write tools. Returns (decision, chosen_index)
+        -- decision is 'accept', 'deny', or 'accept_all'; chosen_index is
+        the clicked button's index into accept_all_choices when decision is
+        'accept_all', else None. See web_approval_ui.WebApprovalUI.show_popup's
+        docstring."""
+
+    @abstractmethod
+    def show_read_popup(
+        self,
+        title: str,
+        preview: dict[str, str],
+        details_text: str,
+        accept_all_choices: list[tuple[str, str]] | None,
+        pii_categories: list[str] | None = None,
+        visibility: dict[str, str] | None = None,
+        claude_reason: str = "",
+        seen_count: int = 0,
+        content_kind: str = "generic",
+        pdf_bytes: bytes = b"",
+        connector: str = "",
+        preview_bytes: bytes = b"",
+        preview_mime_type: str = "",
+        new_info: dict[str, str] | None = None,
+        preview_tables: list[dict] | None = None,
+        preview_blocks: list[dict] | None = None,
+        table_only: bool = False,
+        layout: str = "narrow",
+    ) -> tuple[str, int | None]:
+        """Approval popup for read tools. Returns (decision, chosen_index)
+        -- decision is 'accept', 'deny', or 'accept_all'; chosen_index is
+        the clicked button's index into accept_all_choices when decision is
+        'accept_all', else None. See web_approval_ui.WebApprovalUI.
+        show_read_popup's docstring."""
+
+    @abstractmethod
+    def show_pii_confirmation_popup(self, categories: list[str]) -> bool:
+        """Second-step confirmation for content the PII detector flagged.
+        See web_approval_ui.WebApprovalUI.show_pii_confirmation_popup's
+        docstring."""
+
+    @abstractmethod
+    def show_rule_confirmation_popup(self, description: str) -> bool:
+        """Second-step confirmation after a specific "Always allow" button
+        is clicked. See web_approval_ui.WebApprovalUI.
+        show_rule_confirmation_popup's docstring."""
+
+    @property
+    def deferred_registry(self):  # -> approvals.PendingApprovalRegistry | None
+        """A ``PendingApprovalRegistry`` (approvals.py) this backend is
+        registered with, if it supports the deferred/hold-window protocol --
+        ``None`` (the default) means this backend only ever blocks until a
+        human decides.
+        WebApprovalUI (the only implementation since P10) always overrides
+        this with a real registry; the default stays here for whatever
+        future implementation the seam's own docstring anticipates, in case
+        it has nowhere to send a human a reviewable link either.
+        gate.py checks this property, not the concrete class, to decide
+        whether to apply the deferred protocol -- see that module's
+        docstring."""
+        return None
+
+
+class _UnconfiguredApprovalUI(ApprovalUI):
+    """The bare fallback get_approval_ui() constructs when nothing has
+    called init_approval_ui() yet. Deliberately not WebApprovalUI: this
+    plays the same "inert, no-registry default" role NativeApprovalUI
+    played before P10 -- gate.py's own test suite mostly monkeypatches its
+    module-level show_popup/show_read_popup/etc. wrappers directly, relying
+    on the default ApprovalUI having no deferred_registry (so gated_call()
+    takes the plain blocking path, not the deferred/hold-window one) rather
+    than installing a real ApprovalUI itself. Every method here raises if
+    actually invoked without being monkeypatched or replaced first -- a
+    misconfigured daemon should fail loudly, not silently deny (or block
+    forever on) a real gated call. daemon_main.py always calls
+    init_approval_ui() with a real, config-driven WebApprovalUI before any
+    gated call could reach this."""
+
+    def _unconfigured(self) -> None:
+        raise RuntimeError(
+            "No ApprovalUI configured -- call approval_ui.init_approval_ui() first "
+            "(daemon_main.py always does this at startup)."
+        )
+
+    def show_popup(self, *args, **kwargs):
+        self._unconfigured()
+
+    def show_read_popup(self, *args, **kwargs):
+        self._unconfigured()
+
+    def show_pii_confirmation_popup(self, categories: list[str]) -> bool:
+        self._unconfigured()
+
+    def show_rule_confirmation_popup(self, description: str) -> bool:
+        self._unconfigured()
+
+
+_INSTANCE: ApprovalUI | None = None
+
+
+def get_approval_ui() -> ApprovalUI:
+    """Lazily-constructed singleton -- see _UnconfiguredApprovalUI's own
+    docstring for what the default is and why."""
+    global _INSTANCE
+    if _INSTANCE is None:
+        _INSTANCE = _UnconfiguredApprovalUI()
+    return _INSTANCE
+
+
+def init_approval_ui(ui: ApprovalUI) -> ApprovalUI:
+    global _INSTANCE
+    _INSTANCE = ui
+    return _INSTANCE