cookiesync-cli 0.1.0__py3-none-any.whl

cookiesync/__init__.py

@@ -0,0 +1,3 @@
+"""Sync your browser cookies across machines."""
+
+from __future__ import annotations

cookiesync/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from cookiesync.cli import main
+
+if __name__ == "__main__":
+    main()

cookiesync/cli.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+import anyio
+import click
+from loguru import logger
+
+from cookiesync import helper, paths, state
+from cookiesync.cookie import OutputFormat, StorageState, render
+from cookiesync.cookie.browsers import REGISTRY
+from cookiesync.daemon import rpc
+from cookiesync.daemon.rpc import RpcError
+from cookiesync.daemon.wire import cookie_from_wire
+from cookiesync.helper import HelperState
+from cookiesync.registry import RegistryError, reposync_registry, reposync_self
+from cookiesync.state import BrowserEndpoint, BrowserId, SshTarget, parse_duration
+
+if TYPE_CHECKING:
+    from cookiesync.daemon.wire import Response
+
+
+@click.group()
+@click.version_option(package_name="cookiesync")
+def main() -> None:
+    """Sync your browser cookies across machines."""
+
+
+async def daemon_call(method: str, params: dict | None = None) -> dict | list | None:
+    """Call ``method`` on the resident daemon, raising a clean :class:`click.ClickException` on failure."""
+    try:
+        response = await rpc.call(method, params or {})
+    except RpcError as exc:
+        raise click.ClickException(f"{exc}; is the daemon running? (cookiesync install)") from exc
+    return response_result(response)
+
+
+def response_result(response: Response) -> dict | list | None:
+    if not response.ok:
+        raise click.ClickException(response.error or "daemon error")
+    return response.result
+
+
+@main.group()
+def browser() -> None:
+    """Track the browser profiles cookiesync syncs across hosts."""
+
+
+@browser.command("add")
+@click.argument("host")
+@click.argument("browser_name")
+@click.option("--profile", default="Default", help="Profile directory name.")
+def browser_add(host: str, browser_name: str, profile: str) -> None:
+    """Track a browser profile on HOST for syncing."""
+    anyio.run(add_endpoint, SshTarget(host), browser_name, profile)
+
+
+@browser.command("ls")
+@click.option("--json", "as_json", is_flag=True, help="Emit the endpoints as JSON.")
+def browser_ls(as_json: bool) -> None:
+    """List the tracked browser endpoints."""
+    anyio.run(list_endpoints, as_json)
+
+
+@browser.command("rm")
+@click.argument("host")
+@click.argument("browser_name")
+@click.option("--profile", default="Default", help="Profile directory name.")
+def browser_rm(host: str, browser_name: str, profile: str) -> None:
+    """Stop tracking a browser profile on HOST."""
+    anyio.run(remove_endpoint, SshTarget(host), browser_name, profile)
+
+
+async def add_endpoint(host: SshTarget, browser_name: str, profile: str) -> None:
+    if browser_name not in REGISTRY:
+        raise click.ClickException(f"unknown browser {browser_name!r}; choose from {', '.join(sorted(REGISTRY))}")
+    try:
+        self_target, hosts = await reposync_registry()
+    except RegistryError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if host != self_target and host not in hosts:
+        raise click.ClickException(f"unknown host {host!r}; choose from {', '.join((self_target, *hosts))}")
+    endpoint = BrowserEndpoint(host, BrowserId(browser_name), profile)
+    await state.update(
+        lambda s: replace(
+            s,
+            self_target=self_target,
+            browsers=(*(e for e in s.browsers if e.id != endpoint.id), endpoint),
+        )
+    )
+    logger.debug("tracked {}", endpoint.id)
+    click.echo(f"Tracking {endpoint.id}")
+
+
+async def list_endpoints(as_json: bool) -> None:
+    browsers = (await state.load()).browsers
+    if as_json:
+        click.echo(json.dumps([endpoint.to_json() for endpoint in browsers], indent=2))
+        return
+    click.echo("\n".join(endpoint.id for endpoint in browsers) if browsers else "No tracked browsers.")
+
+
+async def remove_endpoint(host: SshTarget, browser_name: str, profile: str) -> None:
+    target = BrowserEndpoint(host, BrowserId(browser_name), profile).id
+    await state.update(lambda s: replace(s, browsers=tuple(e for e in s.browsers if e.id != target)))
+    logger.debug("untracked {}", target)
+    click.echo(f"Untracked {target}")
+
+
+@main.command()
+def watch() -> None:
+    """Run the resident sync daemon: watch local stores and serve the RPC socket."""
+    anyio.run(run_watch)
+
+
+async def run_watch() -> None:
+    from cookiesync.daemon import Daemon
+
+    logger.debug("starting cookiesync daemon")
+    await (await Daemon.build()).watch()
+
+
+@main.command()
+@click.option("--tick-only", is_flag=True, help="Install only the periodic reconcile tick, not the watch daemon.")
+def install(tick_only: bool) -> None:
+    """Fetch the signed key helper, then install the cookiesync LaunchAgents (watch daemon and reconcile tick)."""
+    anyio.run(run_install, tick_only)
+
+
+async def run_install(tick_only: bool) -> None:
+    from cookiesync.service import LaunchctlLauncher, install
+
+    await ensure_helper()
+    await install(LaunchctlLauncher(), tick_only=tick_only)
+    click.echo("Installed cookiesync agents." if not tick_only else "Installed the cookiesync reconcile tick.")
+
+
+async def ensure_helper() -> None:
+    match await helper.helper_state():
+        case HelperState.OK:
+            click.echo(f"Key helper present and Developer-ID-signed: {paths.helper_app_path()}")
+        case _:
+            click.echo(
+                "Installing the signed key helper via Homebrew (brew install yasyf/tap/cookiesync-keyhelper)…", err=True
+            )
+            try:
+                app = await helper.install_helper()
+            except helper.HelperInstallError as exc:
+                raise click.ClickException(str(exc)) from exc
+            click.echo(f"Installed and verified key helper: {app}")
+
+
+@main.command()
+def doctor() -> None:
+    """Check that the signed Secure-Enclave key helper is installed and Developer-ID-signed."""
+    anyio.run(run_doctor)
+
+
+async def run_doctor() -> None:
+    match await helper.helper_state():
+        case HelperState.OK if await helper.supports_contract():
+            click.echo(f"key helper OK: {paths.helper_app_path()} (Developer ID signed, key-helper contract supported)")
+        case HelperState.OK:
+            raise click.ClickException(
+                f"key helper at {paths.helper_app_path()} is installed but does not support the required "
+                "key-helper contract (likely a stale cask); reinstall the key helper: cookiesync install"
+            )
+        case HelperState.UNSIGNED:
+            raise click.ClickException(
+                f"key helper at {paths.helper_app_path()} is not Developer-ID-signed; "
+                "reinstall the notarized .app via 'cookiesync install'"
+            )
+        case HelperState.MISSING:
+            raise click.ClickException(
+                f"key helper not installed at {paths.helper_app_path()}; run 'cookiesync install' to fetch it"
+            )
+
+
+@main.command()
+def uninstall() -> None:
+    """Remove the cookiesync LaunchAgents."""
+    anyio.run(run_uninstall)
+
+
+async def run_uninstall() -> None:
+    from cookiesync.service import LaunchctlLauncher, uninstall
+
+    await uninstall(LaunchctlLauncher())
+    click.echo("Uninstalled cookiesync agents.")
+
+
+@main.command()
+def reconcile() -> None:
+    """Ask the daemon to run a full reconcile pass over every tracked browser group."""
+    anyio.run(run_reconcile)
+
+
+async def run_reconcile() -> None:
+    result = await daemon_call("reconcile")
+    click.echo(json.dumps(result, indent=2))
+
+
+@main.command("sync")
+@click.option("--browser", "browser_name", required=True, help="The browser group to converge.")
+def sync_cmd(browser_name: str) -> None:
+    """Ask the daemon to converge one browser group across this host and its peers."""
+    anyio.run(run_sync, browser_name)
+
+
+async def run_sync(browser_name: str) -> None:
+    result = await daemon_call("sync", {"browser": browser_name})
+    click.echo(json.dumps(result, indent=2))
+
+
+@main.command()
+@click.option("--browser", "browser_name", default="chrome", show_default=True, help="The browser to authenticate.")
+@click.option("--profile", default="Default", show_default=True, help="The profile to authenticate.")
+@click.option("--ttl", default=None, help="Override the cache TTL (Go-style duration, e.g. 15m).")
+def auth(browser_name: str, profile: str, ttl: str | None) -> None:
+    """Release the Safe Storage key behind one Touch ID tap and cache it for a short window."""
+    anyio.run(run_auth, browser_name, profile, ttl)
+
+
+async def run_auth(browser_name: str, profile: str, ttl: str | None) -> None:
+    if ttl is not None:
+        await state.update(lambda s: replace(s, settings=replace(s.settings, auth_ttl=parse_duration(ttl))))
+    result = await daemon_call("prime_auth", {"browser": browser_name, "profile": profile})
+    click.echo(f"Authenticated {result['endpoint']}.")
+
+
+@main.command()
+@click.argument("url")
+@click.option(
+    "--browser", "browser_name", default="chrome", show_default=True, help="The browser to read cookies from."
+)
+@click.option("--profile", default="Default", show_default=True, help="The profile to read cookies from.")
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice([f.value for f in OutputFormat]),
+    default=OutputFormat.PLAYWRIGHT.value,
+    show_default=True,
+    help="The output wire format.",
+)
+def cookies(url: str, browser_name: str, profile: str, fmt: str) -> None:
+    """Stream URL's cookies in the chosen format, decrypting with the daemon's cached key."""
+    anyio.run(run_cookies, url, browser_name, profile, fmt)
+
+
+async def run_cookies(url: str, browser_name: str, profile: str, fmt: str) -> None:
+    result = await daemon_call("get_cookies", {"url": url, "browser": browser_name, "profile": profile})
+    state_obj = StorageState(tuple(cookie_from_wire(c) for c in result["cookies"]))
+    for line in render(state_obj, OutputFormat(fmt)):
+        click.echo(line)
+
+
+@main.group()
+def rpc_group() -> None:
+    """Low-level RPC client: drive the resident daemon over its unix socket."""
+
+
+main.add_command(rpc_group, name="rpc")
+
+
+@rpc_group.command("extract")
+@click.option("--browser", "browser_name", required=True)
+@click.option("--profile", default="Default")
+@click.option("--origin", default=None)
+def rpc_extract(browser_name: str, profile: str, origin: str | None) -> None:
+    """Return this host's decrypted cookies for a browser as wire records (used by peers over ssh)."""
+    anyio.run(run_rpc_passthrough, "extract", {"browser": browser_name, "profile": profile, "origin": origin})
+
+
+@rpc_group.command("apply")
+@click.option("--browser", "browser_name", required=True)
+@click.option("--profile", default="Default")
+@click.option("--origin", default=None)
+def rpc_apply(browser_name: str, profile: str, origin: str | None) -> None:
+    """Ingest a merged wire cookie array from stdin into this host's store (used by peers over ssh)."""
+    cookies_in = json.loads(click.get_text_stream("stdin").read())
+    anyio.run(
+        run_rpc_passthrough,
+        "apply",
+        {"browser": browser_name, "profile": profile, "origin": origin, "cookies": cookies_in},
+    )
+
+
+@rpc_group.command("sync")
+@click.option("--browser", "browser_name", required=True)
+@click.option("--origin", default=None)
+def rpc_sync(browser_name: str, origin: str | None) -> None:
+    """Ask the daemon to converge one browser group, tagged with the notifying peer's origin."""
+    anyio.run(run_rpc_passthrough, "sync", {"browser": browser_name, "origin": origin})
+
+
+@rpc_group.command("reconcile")
+def rpc_reconcile() -> None:
+    """Ask the daemon to run a full reconcile pass."""
+    anyio.run(run_rpc_passthrough, "reconcile", {})
+
+
+@rpc_group.command("whoami")
+def rpc_whoami() -> None:
+    """Report this host's console session state."""
+    anyio.run(run_rpc_passthrough, "whoami", {})
+
+
+@rpc_group.command("request_consent")
+@click.option("--browser", "browser_name", required=True)
+@click.option("--profile", default="Default")
+@click.option("--nonce", required=True)
+@click.option("--endpoint", required=True)
+def rpc_request_consent(browser_name: str, profile: str, nonce: str, endpoint: str) -> None:
+    """Show the Touch ID prompt for BROWSER here and echo the requester's nonce + endpoint."""
+    anyio.run(
+        run_rpc_passthrough,
+        "request_consent",
+        {"browser": browser_name, "profile": profile, "nonce": nonce, "endpoint": endpoint},
+    )
+
+
+async def run_rpc_passthrough(method: str, params: dict) -> None:
+    click.echo(json.dumps(await daemon_call(method, params)))
+
+
+@main.command(name="self")
+def self_cmd() -> None:
+    """Print this host's own SSH target, as reposync reports it."""
+    anyio.run(run_self)
+
+
+async def run_self() -> None:
+    try:
+        target = await reposync_self()
+    except RegistryError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(target)

cookiesync/cookie/__init__.py

@@ -0,0 +1,20 @@
+"""The cookiesync cookie engine: extract, merge, and apply browser cookies across machines."""
+
+from __future__ import annotations
+
+from cookiesync.cookie.backend import CookieBackend, LocalBackend
+from cookiesync.cookie.browsers import REGISTRY, Browser
+from cookiesync.cookie.consent import Consent, ConsentError, TouchIDConsent
+from cookiesync.cookie.crypto import DecryptError, decrypt_value, derive_key, encrypt_value
+from cookiesync.cookie.merge import merge
+from cookiesync.cookie.models import (
+    AesKey,
+    Cookie,
+    EncryptedRow,
+    Host,
+    HostKey,
+    SafeStorageKey,
+    StorageState,
+)
+from cookiesync.cookie.pipeline import apply, extract
+from cookiesync.cookie.serialize import OutputFormat, render

cookiesync/cookie/backend.py

@@ -0,0 +1,100 @@
+"""The cookie-store seam: where rows are read from, the key obtained, and rows written to.
+
+``CookieBackend`` is the boundary the pipeline talks to, so the same ``extract``/``apply``
+flow runs against the local machine today and an ssh-backed remote tomorrow. ``LocalBackend``
+wires the seam to this machine's stores: it auto-selects the profile with the most applicable
+cookies (raising ``AmbiguousProfile`` when two profiles tie within 50%), filters rows to those
+the browser would send to the host, obtains the Safe Storage key through the consent gate, and
+upserts re-encrypted rows back into the live store.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+from cookiesync.cookie.domains import cookie_applies
+from cookiesync.cookie.stores import (
+    count_applicable,
+    list_profile_dirs,
+    profile_info,
+    read_rows,
+    write_rows,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from cookiesync.cookie.browsers import Browser
+    from cookiesync.cookie.consent import Consent
+    from cookiesync.cookie.models import AesKey, Cookie, EncryptedRow, Host
+
+AMBIGUITY_RATIO = 0.5
+
+
+class AmbiguousProfile(Exception):
+    """Two or more browser profiles match the host within the ambiguity ratio; pass one explicitly."""
+
+
+class NoMatchingProfile(Exception):
+    """No browser profile holds any cookie applicable to the host."""
+
+
+class CookieBackend(Protocol):
+    """Reads encrypted rows, obtains the decryption key, and writes rows for a browser.
+
+    The pipeline holds only this seam, so the local store and a future ssh-backed remote
+    are interchangeable. ``read_rows`` returns rows already filtered to the host and picks
+    the profile when one is not given.
+    """
+
+    async def read_rows(
+        self, browser: Browser, host: Host, *, profile: str | None = None
+    ) -> tuple[EncryptedRow, ...]: ...
+
+    async def obtain_key(self, browser: Browser, *, reason: str) -> AesKey: ...
+
+    async def write_rows(self, browser: Browser, rows: Sequence[Cookie], key: AesKey) -> int: ...
+
+
+async def select_profile(browser: Browser, host: Host) -> str:
+    scored = sorted(
+        (
+            (c, d)
+            for d in await list_profile_dirs(browser)
+            if (c := await count_applicable(browser, profile=d, host=host))
+        ),
+        reverse=True,
+    )
+    match scored:
+        case []:
+            raise NoMatchingProfile(f"no {browser.display} profile has cookies for {host}")
+        case [(top, _), (runner, _), *_] if runner >= AMBIGUITY_RATIO * top:
+            info = await profile_info(browser)
+            cands = "; ".join(f"{d} ({info.get(d, {}).get('email', '?')}: {c})" for c, d in scored)
+            raise AmbiguousProfile(
+                f"multiple {browser.display} profiles match {host} — pass an explicit profile. Candidates: {cands}"
+            )
+        case [(_, winner), *_]:
+            return winner
+
+
+@dataclass(frozen=True, slots=True)
+class LocalBackend:
+    """The local machine's cookie stores behind the consent gate.
+
+    Example:
+        >>> await LocalBackend(TouchIDConsent()).read_rows(REGISTRY[BrowserName("chrome")], Host("x.com"))
+    """
+
+    consent: Consent
+
+    async def read_rows(self, browser: Browser, host: Host, *, profile: str | None = None) -> tuple[EncryptedRow, ...]:
+        chosen = profile or await select_profile(browser, host)
+        return tuple(row for row in await read_rows(browser, chosen) if cookie_applies(row.host_key, host))
+
+    async def obtain_key(self, browser: Browser, *, reason: str) -> AesKey:
+        return await self.consent.obtain_key(browser, reason=reason)
+
+    async def write_rows(self, browser: Browser, rows: Sequence[Cookie], key: AesKey) -> int:
+        return await write_rows(browser, "Default", rows, key)

cookiesync/cookie/browsers.py

@@ -0,0 +1,57 @@
+"""The browser registry: where each supported browser keeps its cookie store and Safe Storage key.
+
+A ``Browser`` resolves a profile's on-disk paths (cookie DB, Local State) and names
+the Keychain service holding its Safe Storage password.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NewType
+
+BrowserName = NewType("BrowserName", str)
+
+APPLICATION_SUPPORT = Path.home() / "Library" / "Application Support"
+
+
+@dataclass(frozen=True, slots=True)
+class Browser:
+    """A Chromium-family browser and its on-disk layout.
+
+    Example:
+        >>> REGISTRY["chrome"].cookies_db("Default")
+    """
+
+    name: BrowserName
+    display: str
+    data_root: Path
+    keychain_service: str
+
+    def profile_dir(self, profile: str) -> Path:
+        """The directory holding one profile's state under this browser's data root."""
+        return self.data_root / profile
+
+    def cookies_db(self, profile: str) -> Path:
+        """The SQLite cookie store for one profile."""
+        return self.profile_dir(profile) / "Cookies"
+
+    def local_state(self) -> Path:
+        """The ``Local State`` JSON file at this browser's data root."""
+        return self.data_root / "Local State"
+
+
+REGISTRY: dict[BrowserName, Browser] = {
+    BrowserName("chrome"): Browser(
+        name=BrowserName("chrome"),
+        display="Chrome",
+        data_root=APPLICATION_SUPPORT / "Google" / "Chrome",
+        keychain_service="Chrome Safe Storage",
+    ),
+    BrowserName("arc"): Browser(
+        name=BrowserName("arc"),
+        display="Arc",
+        data_root=APPLICATION_SUPPORT / "Arc" / "User Data",
+        keychain_service="Arc Safe Storage",
+    ),
+}

cookiesync/cookie/consent.py

@@ -0,0 +1,128 @@
+"""Secure-Enclave-bound consent: obtain the Safe Storage AES key behind one Touch ID tap.
+
+The legacy approach was consent theater — a cosmetic ``LAContext`` gate in front of a
+sticky "Always Allow" ``/usr/bin/security`` read that goes silent after the first run.
+``TouchIDConsent`` instead stores the Safe Storage password in a data-protection
+keychain item bound to biometry-or-passcode, so every retrieval forces a genuine
+biometric (or device-passcode) evaluation through the keychain. On a host with neither
+biometrics nor a passcode (headless, no Touch ID), it falls back to the device-unlock
+``security`` read.
+
+The biometric vault and re-store run inside the installed, Developer-ID-signed
+``cookiesync-keyhelper.app`` (``vault-status`` / ``vault-retrieve`` / ``vault-enroll``).
+An ad-hoc helper is SIGKILLed at exec by AMFI, so a missing helper fails closed rather
+than degrading to an unsigned build — see :func:`cookiesync.paths.require_helper`.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NamedTuple, Protocol
+
+import anyio
+
+from cookiesync import paths
+from cookiesync.cookie.crypto import derive_key
+from cookiesync.cookie.models import AesKey, SafeStorageKey
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from cookiesync.cookie.browsers import Browser
+
+SECURITY = "/usr/bin/security"
+REASON_CAP = 160
+
+
+class VaultStatus(NamedTuple):
+    returncode: int
+    has_passcode: bool
+    has_vault: bool
+
+
+class ConsentError(Exception):
+    """The user explicitly declined the Touch ID / passcode prompt, or the vault read failed."""
+
+
+def compose_reason(host: str, reason: str) -> str:
+    """Touch ID prompt text: domain first, the caller's reason as a 'to …' clause.
+
+    ``reason`` is collapsed to a single line and capped, since it surfaces verbatim in
+    a security dialog.
+    """
+    return f"access your {host} session to {' '.join(reason.split())[:REASON_CAP]}"
+
+
+class Consent(Protocol):
+    """Obtains the Safe Storage AES key for a browser, gating on the user's consent."""
+
+    async def obtain_key(self, browser: Browser, *, reason: str) -> AesKey: ...
+
+    async def obtain_key_unprompted(self, browser: Browser) -> AesKey: ...
+
+
+@dataclass(frozen=True, slots=True)
+class TouchIDConsent:
+    """A Secure-Enclave-bound key vault: one biometric tap unlocks the cached key.
+
+    Example:
+        >>> await TouchIDConsent().obtain_key(REGISTRY[BrowserName("chrome")], reason="post a tweet")
+    """
+
+    async def obtain_key_unprompted(self, browser: Browser) -> AesKey:
+        """Release ``browser``'s key non-interactively, via a bare Keychain read — no Touch ID.
+
+        For the owning host *only*, and *only* after a verified routed approval from the
+        active-session peer has already gated the release: this performs the unlocked
+        ``security`` read with no user-presence prompt, so the user-presence check must
+        have happened over the routed-consent handshake first.
+        """
+        return derive_key(await self.read_safe_storage(browser.keychain_service))
+
+    async def obtain_key(self, browser: Browser, *, reason: str) -> AesKey:
+        helper = paths.require_helper()
+        vault = f"cookiesync.vault.{browser.name}"
+        env = os.environ | {"COOKIESYNC_TOUCHID_REASON": compose_reason(browser.display, reason)}
+
+        status = await anyio.run_process([str(helper), "vault-status", vault], check=False)
+        match VaultStatus(status.returncode, b"passcode=true" in status.stdout, b"vault=true" in status.stdout):
+            case VaultStatus(returncode=2, has_passcode=False):
+                return derive_key(await self.read_safe_storage(browser.keychain_service))
+            case VaultStatus(has_vault=True):
+                return derive_key(await self.retrieve(helper, vault, browser.keychain_service, env=env))
+            case _:
+                await self.enroll(helper, vault, browser.keychain_service)
+                return derive_key(await self.retrieve(helper, vault, browser.keychain_service, env=env))
+
+    async def retrieve(
+        self, helper: Path, vault: str, safe_storage_service: str, *, env: dict[str, str]
+    ) -> SafeStorageKey:
+        result = await anyio.run_process([str(helper), "vault-retrieve", vault], check=False, env=env)
+        match result.returncode:
+            case 0:
+                return SafeStorageKey(result.stdout.decode("utf-8"))
+            case 1:
+                raise ConsentError("Touch ID authentication was cancelled or denied")
+            case _:
+                # errSecItemNotFound / errSecAuthFailed: the biometryCurrentSet ACL
+                # invalidated (the fingerprint set changed). Re-enroll once, then retry.
+                await self.enroll(helper, vault, safe_storage_service)
+                second = await anyio.run_process([str(helper), "vault-retrieve", vault], check=False, env=env)
+                if second.returncode == 0:
+                    return SafeStorageKey(second.stdout.decode("utf-8"))
+                raise ConsentError("Touch ID vault retrieval failed after re-enrollment")
+
+    async def enroll(self, helper: Path, vault: str, safe_storage_service: str) -> None:
+        result = await anyio.run_process([str(helper), "vault-enroll", vault, safe_storage_service], check=False)
+        if result.returncode != 0:
+            raise ConsentError(
+                f"could not enroll the Touch ID vault for {safe_storage_service!r} "
+                f"(exit {result.returncode}: {result.stderr.decode().strip() or 'no detail'})"
+            )
+
+    async def read_safe_storage(self, service: str) -> SafeStorageKey:
+        result = await anyio.run_process([SECURITY, "find-generic-password", "-w", "-s", service], check=False)
+        if result.returncode != 0:
+            raise ConsentError(f"could not read '{service}' from the Keychain (denied or missing)")
+        return SafeStorageKey(result.stdout.decode("utf-8").strip())