cookiesync-cli 0.1.0__py3-none-any.whl

cookiesync/cookie/stores.py

@@ -0,0 +1,218 @@
+"""Schema-version-aware async I/O against Chrome's SQLite cookie store.
+
+Reads copy the live ``Cookies`` DB (plus its ``-wal``/``-shm``/``-journal`` sidecars)
+into a private temp dir and open the copy read-write, so a running browser is never
+disturbed and the WAL checkpoints into the copy before we ``SELECT``. Writes go to the
+live DB, best-effort: a short ``busy_timeout`` plus a soft-busy return on a locked DB,
+never a forced clobber.
+
+Chrome's cookie schema drifts across versions: v18 carries ``is_same_party`` and a
+``UNIQUE(host_key, top_frame_site_key, name, path)`` index, while v24 drops
+``is_same_party``, adds ``source_type`` + ``has_cross_site_ancestor``, and widens the
+unique index to include ``has_cross_site_ancestor``, ``source_scheme``, and
+``source_port``. Every operation introspects the actual table and unique index via
+``PRAGMA table_info`` / ``PRAGMA index_list`` / ``PRAGMA index_info`` rather than
+hardcoding one column set.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import aiosqlite
+
+from cookiesync.cookie.crypto import encrypt_value
+from cookiesync.cookie.domains import cookie_applies
+from cookiesync.cookie.models import (
+    ChromeMicros,
+    EncryptedRow,
+    Host,
+    HostKey,
+    unix_to_chrome_micros,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from cookiesync.cookie.browsers import Browser
+    from cookiesync.cookie.models import AesKey, Cookie
+
+SIDECAR_SUFFIXES = ("-wal", "-shm", "-journal")
+
+BUSY_TIMEOUT_MS = 250
+
+ROW_FIELD_DEFAULTS: dict[str, object] = {
+    "encrypted_value": b"",
+    "value": "",
+    "source_scheme": 2,
+    "source_port": 443,
+    "top_frame_site_key": "",
+    "has_cross_site_ancestor": 0,
+}
+
+
+def _to_micros(value: int) -> ChromeMicros:
+    return ChromeMicros(int(value))
+
+
+def _row_from_columns(columns: tuple[str, ...], values: tuple[object, ...]) -> EncryptedRow:
+    cells = ROW_FIELD_DEFAULTS | dict(zip(columns, values, strict=True))
+    return EncryptedRow(
+        host_key=HostKey(cells["host_key"]),
+        name=cells["name"],
+        encrypted_value=bytes(ev) if (ev := cells["encrypted_value"]) is not None else b"",
+        value=cells["value"] or "",
+        path=cells["path"],
+        expires_utc=_to_micros(cells["expires_utc"]),
+        last_update_utc=_to_micros(cells.get("last_update_utc", 0)),
+        creation_utc=_to_micros(cells["creation_utc"]),
+        is_secure=bool(cells["is_secure"]),
+        is_httponly=bool(cells["is_httponly"]),
+        samesite=int(cells["samesite"]),
+        source_scheme=int(cells["source_scheme"]),
+        source_port=int(cells["source_port"]),
+        top_frame_site_key=str(cells["top_frame_site_key"]),
+        has_cross_site_ancestor=int(cells["has_cross_site_ancestor"]),
+    )
+
+
+async def _table_columns(db: aiosqlite.Connection) -> tuple[str, ...]:
+    async with db.execute("PRAGMA table_info(cookies)") as cur:
+        return tuple(row[1] for row in await cur.fetchall())
+
+
+async def _unique_index_columns(db: aiosqlite.Connection) -> tuple[str, ...]:
+    async with db.execute("PRAGMA index_list(cookies)") as cur:
+        indexes = await cur.fetchall()
+    name = next(idx[1] for idx in indexes if idx[2] and not idx[4])
+    async with db.execute(f"PRAGMA index_info({name})") as cur:
+        return tuple(col[2] for col in await cur.fetchall())
+
+
+def _copy_with_sidecars(db: Path, dest_dir: Path) -> Path:
+    copy = dest_dir / "Cookies"
+    shutil.copy2(db, copy)
+    for suffix in SIDECAR_SUFFIXES:
+        if (side := Path(f"{db}{suffix}")).is_file():
+            shutil.copy2(side, f"{copy}{suffix}")
+    return copy
+
+
+async def read_rows(browser: Browser, profile: str) -> tuple[EncryptedRow, ...]:
+    """Every cookie row in ``profile`` as raw ``EncryptedRow``s, read off a private copy.
+
+    The live ``Cookies`` DB and its WAL/journal sidecars are copied to a temp dir and the
+    copy is opened read-write so SQLite checkpoints the WAL before the read. Only columns
+    present in this store's schema are selected; absent columns fall back to their defaults.
+    """
+    tmpdir = Path(tempfile.mkdtemp(prefix="cookiesync-"))
+    try:
+        copy = _copy_with_sidecars(browser.cookies_db(profile), tmpdir)
+        async with aiosqlite.connect(copy) as db:
+            columns = await _table_columns(db)
+            async with db.execute(f"SELECT {', '.join(columns)} FROM cookies") as cur:
+                rows = await cur.fetchall()
+            return tuple(_row_from_columns(columns, tuple(values)) for values in rows)
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+async def list_profile_dirs(browser: Browser) -> tuple[str, ...]:
+    """Profile directory names under ``browser`` that hold a ``Cookies`` DB, sorted."""
+    root = browser.data_root
+    return tuple(sorted(c.name for c in root.iterdir() if c.is_dir() and browser.cookies_db(c.name).is_file()))
+
+
+async def count_applicable(browser: Browser, profile: str, host: Host) -> int:
+    """How many cookies in ``profile`` a browser would send to ``host`` (no decryption)."""
+    return sum(cookie_applies(row.host_key, host) for row in await read_rows(browser, profile))
+
+
+async def profile_info(browser: Browser) -> dict[str, dict[str, str]]:
+    """Map each profile directory name to its ``{email, name}`` from ``Local State``.
+
+    Read from the browser's ``Local State`` JSON under ``profile.info_cache``: ``email``
+    comes from ``user_name`` and ``name`` from ``gaia_name`` (falling back to ``name``).
+    """
+    cache = json.loads(browser.local_state().read_text()).get("profile", {}).get("info_cache", {})
+    return {
+        name: {
+            "email": info.get("user_name", ""),
+            "name": info.get("gaia_name", "") or info.get("name", ""),
+        }
+        for name, info in cache.items()
+    }
+
+
+def _insert_values(cookie: Cookie, encrypted: bytes) -> dict[str, object]:
+    creation = cookie.creation_utc if cookie.creation_utc > 0 else unix_to_chrome_micros(time.time())
+    has_expires = int(cookie.expires_utc > 0)
+    return {
+        "creation_utc": int(creation),
+        "host_key": cookie.host_key,
+        "top_frame_site_key": cookie.top_frame_site_key,
+        "name": cookie.name,
+        "value": "",
+        "encrypted_value": encrypted,
+        "path": cookie.path,
+        "expires_utc": int(cookie.expires_utc),
+        "is_secure": int(cookie.is_secure),
+        "is_httponly": int(cookie.is_httponly),
+        "last_access_utc": int(cookie.last_update_utc),
+        "has_expires": has_expires,
+        "is_persistent": has_expires,
+        "priority": 1,
+        "samesite": cookie.samesite,
+        "source_scheme": cookie.source_scheme,
+        "source_port": cookie.source_port,
+        "last_update_utc": int(cookie.last_update_utc),
+        "source_type": 0,
+        "has_cross_site_ancestor": cookie.has_cross_site_ancestor,
+        "is_same_party": 0,
+    }
+
+
+def _upsert_sql(columns: tuple[str, ...], conflict: tuple[str, ...]) -> str:
+    cols = ", ".join(columns)
+    placeholders = ", ".join(f":{c}" for c in columns)
+    updates = ", ".join(
+        f"{c} = excluded.{c}"
+        for c in ("encrypted_value", "value", "expires_utc", "last_update_utc", "is_secure", "is_httponly", "samesite")
+        if c in columns
+    )
+    return (
+        f"INSERT INTO cookies ({cols}) VALUES ({placeholders}) "
+        f"ON CONFLICT({', '.join(conflict)}) DO UPDATE SET {updates}"
+    )
+
+
+async def write_rows(browser: Browser, profile: str, cookies: Sequence[Cookie], key: AesKey) -> int:
+    """Encrypt and upsert ``cookies`` into ``profile``'s live ``Cookies`` DB; return rows written.
+
+    Each value is re-encrypted into a ``v10`` blob (the plaintext ``value`` column is left
+    empty) and written with ``INSERT ... ON CONFLICT(<this store's real unique index>) DO
+    UPDATE``, so a re-synced cookie collapses onto its existing row. The cookie's own
+    ``last_update_utc`` and ``creation_utc`` are preserved, never stamped to "now". On a
+    locked database this returns ``-1`` (soft busy) rather than forcing a write.
+    """
+    db_path = browser.cookies_db(profile)
+    async with aiosqlite.connect(db_path) as db:
+        await db.execute(f"PRAGMA busy_timeout = {BUSY_TIMEOUT_MS}")
+        columns = await _table_columns(db)
+        conflict = await _unique_index_columns(db)
+        sql = _upsert_sql(columns, conflict)
+        try:
+            for cookie in cookies:
+                values = _insert_values(cookie, encrypt_value(cookie.value, key, cookie.host_key))
+                await db.execute(sql, {c: values[c] for c in columns})
+            await db.commit()
+        except aiosqlite.OperationalError as exc:
+            if "locked" not in str(exc):
+                raise
+            return -1
+    return len(cookies)

cookiesync/daemon/__init__.py

@@ -0,0 +1,13 @@
+"""The cookiesync sync daemon: active-session detection, the watch/sync loops, and the unix-socket RPC.
+
+Public surface re-exported here is what the CLI and RPC layers call; everything else
+in the package stays internal.
+"""
+
+from __future__ import annotations
+
+from cookiesync.daemon.rpc import Dispatcher, RpcError, call, serve
+from cookiesync.daemon.server import AuthRequired, CachedKeySource, Daemon
+from cookiesync.daemon.session import has_active_session, session_summary
+from cookiesync.daemon.sync import NeedsAuth, converge, reconcile
+from cookiesync.daemon.wire import Request, Response, cookie_from_wire, cookie_to_wire

cookiesync/daemon/backend_ssh.py

@@ -0,0 +1,70 @@
+"""The ssh-backed peer source: drive a remote host's daemon to read and write its cookies.
+
+A peer's cookies never leave its machine encrypted — decryption happens *remotely*, in the
+remote daemon's live GUI session, so the Safe Storage key never crosses the wire.
+``SshBackend`` is the client side of that exchange and the peer half of the sync
+:class:`~cookiesync.daemon.sync.Source` seam: ``extract`` shells out to ``cookiesync rpc
+extract`` on the peer and parses the wire cookie records it streams back; ``apply`` pipes
+the merged wire payload to ``cookiesync rpc apply`` on the peer's stdin. The remote ``rpc``
+command is wired by the integrator; this module owns the client and the payload shape.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from cookiesync.daemon.sync import Extracted
+from cookiesync.daemon.wire import cookie_from_wire, cookie_to_wire
+from cookiesync.transport import shell_quote, ssh
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from cookiesync.cookie.models import Cookie
+    from cookiesync.state import BrowserId, SshTarget
+
+
+@dataclass(frozen=True, slots=True)
+class SshBackend:
+    """A peer host's cookie store, reached by driving its daemon over ssh.
+
+    The peer decrypts in its own GUI session, so cookies cross the wire already decrypted
+    and the peer's Safe Storage key never leaves its machine. ``origin`` is this host's own
+    target, forwarded on every call so the peer's daemon can suppress the echo back to us.
+
+    Example:
+        >>> SshBackend(SshTarget("me@laptop"), origin=self_target)
+    """
+
+    target: SshTarget
+    origin: SshTarget
+
+    async def extract(self, browser: BrowserId, profile: str) -> Extracted:
+        """Extract the peer's decrypted cookies for ``browser``/``profile``."""
+        payload = json.loads(
+            await ssh(
+                self.target,
+                "cookiesync rpc extract"
+                f" --browser {shell_quote(browser)} --profile {shell_quote(profile)}"
+                f" --origin {shell_quote(self.origin)}",
+            )
+        )
+        return Extracted(tuple(cookie_from_wire(c) for c in payload["cookies"]))
+
+    async def apply(self, browser: BrowserId, profile: str, cookies: Sequence[Cookie]) -> int:
+        """Apply the merged ``cookies`` to the peer's ``browser``/``profile`` store, returning rows written.
+
+        The merged set is piped as a JSON array of wire records to the peer's
+        ``cookiesync rpc apply`` stdin; the peer re-encrypts with its own key.
+        """
+        return json.loads(
+            await ssh(
+                self.target,
+                "cookiesync rpc apply"
+                f" --browser {shell_quote(browser)} --profile {shell_quote(profile)}"
+                f" --origin {shell_quote(self.origin)}",
+                stdin=json.dumps([cookie_to_wire(c) for c in cookies]).encode(),
+            )
+        )["applied"]

cookiesync/daemon/cache.py

@@ -0,0 +1,113 @@
+"""Short-TTL, Secure-Enclave-wrapped cache for derived AES keys.
+
+The sync daemon derives a browser's Safe Storage key behind one Touch ID tap, then
+reuses it for a brief window so a burst of operations needs only a single prompt. The
+plaintext key lives in process memory for that window, but the AT-REST cache bytes are
+Secure-Enclave-wrapped: a leaked cache blob or a core dump is useless off-box, since
+only the live per-boot Enclave key can unwrap it.
+
+:class:`SecureEnclaveWrapper` drives the installed, Developer-ID-signed
+``cookiesync-keyhelper.app`` (``cache-newkey`` / ``cache-wrap`` / ``cache-unwrap`` /
+``cache-dropkey``). An ad-hoc helper is refused the Enclave, so a missing helper fails
+closed — see :func:`cookiesync.paths.require_helper`. Tests inject a :class:`Wrapper`
+double and a clock, so the cache logic is exercised without any macOS API.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+import anyio
+
+from cookiesync import paths
+
+
+class Wrapper(Protocol):
+    """Wraps and unwraps key bytes so the at-rest cache value is opaque off-box."""
+
+    async def wrap(self, plaintext: bytes) -> bytes: ...
+
+    async def unwrap(self, blob: bytes) -> bytes: ...
+
+
+@dataclass(frozen=True, slots=True)
+class SecureEnclaveWrapper:
+    """Wraps key bytes against a per-boot ephemeral Secure-Enclave P-256 key.
+
+    The Enclave key is created in :meth:`open` (one random label per process) and
+    destroyed in :meth:`close`, so wrapped blobs are unrecoverable after the daemon
+    exits or the machine reboots.
+
+    Example:
+        >>> wrapper = await SecureEnclaveWrapper.open()
+        >>> blob = await wrapper.wrap(key)
+        >>> assert await wrapper.unwrap(blob) == key
+        >>> await wrapper.close()
+    """
+
+    helper: Path
+    label: str = field(default_factory=lambda: secrets.token_hex(8))
+
+    @classmethod
+    async def open(cls) -> SecureEnclaveWrapper:
+        wrapper = cls(paths.require_helper())
+        await anyio.run_process([str(wrapper.helper), "cache-newkey", wrapper.label])
+        return wrapper
+
+    async def wrap(self, plaintext: bytes) -> bytes:
+        return (await anyio.run_process([str(self.helper), "cache-wrap", self.label], input=plaintext)).stdout
+
+    async def unwrap(self, blob: bytes) -> bytes:
+        return (await anyio.run_process([str(self.helper), "cache-unwrap", self.label], input=blob)).stdout
+
+    async def close(self) -> None:
+        await anyio.run_process([str(self.helper), "cache-dropkey", self.label])
+
+
+@dataclass(frozen=True, slots=True)
+class Entry:
+    blob: bytes
+    expires_at: float
+
+
+@dataclass(slots=True)
+class KeyCache:
+    """A short-TTL cache of derived AES keys, each stored only as a wrapped blob.
+
+    ``put`` wraps a key and records its expiry; ``get`` unwraps transiently and returns
+    ``None`` once the entry is expired or evicted. The plaintext is never persisted to
+    disk and never logged. The clock is injectable for tests.
+
+    Example:
+        >>> cache = KeyCache(await SecureEnclaveWrapper.open())
+        >>> await cache.put(endpoint.id, key, ttl=30.0)
+        >>> assert await cache.get(endpoint.id) == key
+    """
+
+    wrapper: Wrapper
+    now: Callable[[], float] = time.monotonic
+    entries: dict[str, Entry] = field(default_factory=dict)
+
+    async def put(self, endpoint_id: str, key: bytes, ttl: float) -> None:
+        self.entries[endpoint_id] = Entry(await self.wrapper.wrap(key), self.now() + ttl)
+
+    async def get(self, endpoint_id: str) -> bytes | None:
+        match self.entries.get(endpoint_id):
+            case None:
+                return None
+            case Entry(expires_at=expires_at) if self.now() >= expires_at:
+                del self.entries[endpoint_id]
+                return None
+            case Entry(blob=blob):
+                return await self.wrapper.unwrap(blob)
+
+    def evict(self, endpoint_id: str) -> None:
+        self.entries.pop(endpoint_id, None)
+
+    def evict_all(self) -> None:
+        self.entries.clear()

cookiesync/daemon/engine.py

@@ -0,0 +1,195 @@
+"""The watch engine: debounce a cookie-store write burst into one converge, with anti-echo.
+
+A Chrome/Arc cookie write lands as a burst across the ``Cookies`` DB and its ``-wal``/
+``-shm`` sidecars. The engine coalesces that burst, per endpoint, into a single
+``evaluate`` once the store has been quiet for ``settings.watch_debounce``, then fires the
+injected ``notify`` callback so the sync layer converges that endpoint with its peers.
+
+Two filters keep the engine from chasing its own tail:
+
+* **Anti-echo.** ``evaluate`` fingerprints the endpoint's *logical* cookie set via
+  :func:`logical_digest` — sorted ``(host_key, name, path, last_update_utc)`` tuples, cheap
+  and decryption-free — and compares it to the last digest the engine acted on. The sync
+  layer records the digest of the very set it is about to write via :meth:`record_applied`
+  just before writing; because the store preserves each cookie's ``last_update_utc``, the
+  self-induced write reproduces that same digest and is recognized as a no-op. Only a
+  genuinely new digest is recorded (*before* notifying) and notified.
+* **Idle gate.** A store whose ``Cookies`` wall-clock mtime is within
+  ``settings.idle_threshold`` is a browser actively writing; the engine debounces but does
+  not notify until it settles.
+
+The watcher source, clocks, mtime reader, digest function, and notify callback are all
+injected, so the debounce/anti-echo/idle logic runs in unit tests with no real filesystem,
+browser, or macOS API.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, NewType, Protocol
+
+import anyio
+
+from cookiesync.cookie import REGISTRY
+from cookiesync.cookie.browsers import BrowserName
+from cookiesync.cookie.stores import read_rows
+
+if TYPE_CHECKING:
+    from cookiesync.cookie.browsers import Browser
+    from cookiesync.state import BrowserEndpoint, Settings
+
+Digest = NewType("Digest", str)
+
+type AwatchSource = Callable[[BrowserEndpoint], AsyncIterator[object]]
+type Notify = Callable[[BrowserEndpoint], Awaitable[None]]
+type DigestFn = Callable[[BrowserEndpoint], Awaitable[Digest]]
+type Mtime = Callable[[BrowserEndpoint], Awaitable[float]]
+type Sleep = Callable[[float], Awaitable[None]]
+
+
+class LogicalRow(Protocol):
+    """The fields :func:`logical_digest` keys on; satisfied by both ``Cookie`` and ``EncryptedRow``."""
+
+    host_key: str
+    name: str
+    path: str
+    last_update_utc: int
+
+
+def logical_digest(items: Iterable[LogicalRow]) -> Digest:
+    """A cheap, decryption-free digest of a cookie set's logical identity.
+
+    Hashes the sorted ``(host_key, name, path, last_update_utc)`` tuples of every item. It
+    ignores encrypted values and schema-only columns, so it changes exactly when the logical
+    cookie set does. The sync layer digests the set it is about to write and the engine
+    fingerprints the store after the write; because ``last_update_utc`` is preserved on write,
+    the two agree and the induced filesystem event is recognized as the engine's own echo.
+    """
+    payload = "\x00".join(
+        f"{item.host_key}\x1f{item.name}\x1f{item.path}\x1f{item.last_update_utc}"
+        for item in sorted(items, key=lambda i: (i.host_key, i.name, i.path, i.last_update_utc))
+    )
+    return Digest(hashlib.sha256(payload.encode("utf-8")).hexdigest())
+
+
+def endpoint_browser(endpoint: BrowserEndpoint) -> Browser:
+    """The :class:`~cookiesync.cookie.browsers.Browser` an endpoint names."""
+    return REGISTRY[BrowserName(endpoint.browser)]
+
+
+def watch_dir(endpoint: BrowserEndpoint) -> object:
+    """The directory holding an endpoint's ``Cookies`` DB and its WAL/SHM sidecars."""
+    return endpoint_browser(endpoint).profile_dir(endpoint.profile)
+
+
+async def fingerprint(endpoint: BrowserEndpoint) -> Digest:
+    """The :func:`logical_digest` of an endpoint's store, read off its raw rows.
+
+    Decryption-free: it reads every ``EncryptedRow`` and digests their logical identity, so
+    it changes exactly when the logical cookie set does — which is what the anti-echo
+    comparison turns on.
+    """
+    return logical_digest(await read_rows(endpoint_browser(endpoint), endpoint.profile))
+
+
+async def cookies_mtime(endpoint: BrowserEndpoint) -> float:
+    """The Unix mtime of an endpoint's live ``Cookies`` DB."""
+    return (await anyio.Path(endpoint_browser(endpoint).cookies_db(endpoint.profile)).stat()).st_mtime
+
+
+async def watch_endpoint(endpoint: BrowserEndpoint) -> AsyncIterator[object]:
+    """Yield once per ``watchfiles`` change batch on an endpoint's profile directory."""
+    from watchfiles import awatch
+
+    async for changes in awatch(watch_dir(endpoint)):
+        yield changes
+
+
+@dataclass(slots=True)
+class EndpointState:
+    deadline: float = 0.0
+    seq: int = 0
+    last_applied: Digest | None = None
+
+
+@dataclass(slots=True)
+class Engine:
+    """Debounces each local endpoint's cookie-store writes into anti-echoed converges.
+
+    ``run`` opens one watcher per endpoint and, for each, coalesces a burst of filesystem
+    events into a single ``evaluate`` after ``settings.watch_debounce`` of quiet. ``evaluate``
+    fingerprints the endpoint, skips the self-induced echo and an actively-writing store,
+    and otherwise records the new digest before invoking ``notify``. The sync layer calls
+    :meth:`record_applied` right before it writes a cookie set back, so the write it triggers
+    is recognized as the engine's own echo.
+
+    ``now`` is a monotonic clock for the debounce deadline; ``wall`` is wall-clock time,
+    compared against the store's wall-clock mtime for the idle gate. The watcher source,
+    both clocks, mtime reader, digest function, and notify callback are injected, so the
+    whole core runs in tests without a real store or browser.
+
+    Example:
+        >>> engine = Engine(settings, notify=converge)
+        >>> async with anyio.create_task_group() as tg:
+        ...     tg.start_soon(engine.run, endpoints)
+    """
+
+    settings: Settings
+    notify: Notify
+    watch: AwatchSource = watch_endpoint
+    digest: DigestFn = fingerprint
+    mtime: Mtime = cookies_mtime
+    now: Callable[[], float] = time.monotonic
+    wall: Callable[[], float] = time.time
+    sleep: Sleep = anyio.sleep
+    states: dict[str, EndpointState] = field(default_factory=dict)
+
+    def state(self, endpoint: BrowserEndpoint) -> EndpointState:
+        return self.states.setdefault(endpoint.id, EndpointState())
+
+    def current_digest(self, endpoint: BrowserEndpoint) -> Digest | None:
+        """The last digest the engine acted on or the sync layer recorded for ``endpoint``."""
+        return self.state(endpoint).last_applied
+
+    def record_applied(self, endpoint_id: str, digest: Digest) -> None:
+        """Record ``digest`` as the endpoint's applied state so the write it triggers is a no-op.
+
+        The sync layer calls this immediately before it writes a merged cookie set back to a
+        store; the watcher event that write produces then fingerprints to ``digest`` and is
+        suppressed as the engine's own echo.
+        """
+        self.states.setdefault(endpoint_id, EndpointState()).last_applied = digest
+
+    async def run(self, endpoints: tuple[BrowserEndpoint, ...]) -> None:
+        """Watch every endpoint concurrently until the surrounding task group is cancelled."""
+        async with anyio.create_task_group() as tg:
+            for endpoint in endpoints:
+                tg.start_soon(self.watch_loop, endpoint)
+
+    async def watch_loop(self, endpoint: BrowserEndpoint) -> None:
+        debounce = self.settings.watch_debounce.total_seconds()
+        state = self.state(endpoint)
+        async with anyio.create_task_group() as tg:
+            async for _ in self.watch(endpoint):
+                state.seq += 1
+                state.deadline = self.now() + debounce
+                tg.start_soon(self.fire_after, endpoint, state.seq)
+
+    async def fire_after(self, endpoint: BrowserEndpoint, seq: int) -> None:
+        state = self.state(endpoint)
+        await self.sleep(self.settings.watch_debounce.total_seconds())
+        if seq == state.seq and self.now() >= state.deadline:
+            await self.evaluate(endpoint)
+
+    async def evaluate(self, endpoint: BrowserEndpoint) -> None:
+        digest = await self.digest(endpoint)
+        state = self.state(endpoint)
+        if digest == state.last_applied:
+            return
+        if self.wall() - await self.mtime(endpoint) < self.settings.idle_threshold.total_seconds():
+            return
+        state.last_applied = digest
+        await self.notify(endpoint)