diff --git a/.gitignore b/.gitignore
index 0c72982..8840c15 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,7 @@ lerna-debug.log*
 
 node_modules
 dist
+dist-firefox
 dist.zip
 dist-ssr
 coverage
diff --git a/CLAUDE.md b/CLAUDE.md
index 3ac5424..2ceb070 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,6 +11,8 @@ A Manifest V3 browser extension (Chrome, Edge, Firefox) for proxy profile manage
 ```bash
 npm run build           # Type-check (vue-tsc) + build for Chrome/Edge
 npm run build:firefox   # Type-check + build for Firefox (transforms manifest)
+npm run build:preview   # Chrome build against the preview server (northernlight.byte.vet), fixed dev extension ID
+npm run build:preview:firefox  # The same for Firefox, into dist-firefox/ (so it doesn't replace the Chrome dist/)
 npm run dev             # Vite dev server
 npm test                # Run vitest in watch mode
 npm run coverage        # Single run with coverage report
@@ -20,6 +22,8 @@ npm run test:e2e            # Build into .e2e-build/, then run all e2e tests
 npm run test:e2e:chromium   # Chromium suite only (Playwright)
 npm run test:e2e:firefox    # Firefox smoke suite only (Selenium + geckodriver)
 npm run test:e2e:typecheck  # Type-check e2e/ (not covered by vue-tsc)
+npm run test:e2e:live       # Live sync smoke vs northernlight.byte.vet: headed, you sign in twice; never in CI
+npm run sync:api-types      # Regenerate src/services/sync/api.gen.ts from docs/sync-api.openapi.yaml
 E2E_SKIP_BUILD=1 npx playwright test -c e2e --project=chromium e2e/specs/pac.e2e.ts  # Reuse the last build, one spec
 ```
 
@@ -64,7 +68,7 @@ The core complexity lives here:
 
 ### Profile system (`src/services/profile.ts`)
 
-Profiles are stored in `chrome.storage.local` under key `"profiles"`. Types: `ProfileSimple` (proxy/pac), `ProfilePreset` (system/direct), `ProfileAutoSwitch` (rule-based routing). System profiles `DIRECT` and `SYSTEM` have fixed IDs `"direct"` and `"system"`. `onProfileUpdate(cb)` fires in every extension context with the new and old profiles.
+Profiles are stored in `chrome.storage.local` under key `"profiles"`. Write them only through `saveProfile`/`saveManyProfiles`/`deleteProfile`/`updateProfiles`: they hold a Web Lock (`withLock` in `utils.ts`) across extension contexts, so the config page, PAC refresh and sync don't overwrite each other. Deleting the active profile (here or by sync) switches the proxy to Direct (`refreshProxy`). Types: `ProfileSimple` (proxy/pac), `ProfilePreset` (system/direct), `ProfileAutoSwitch` (rule-based routing). System profiles `DIRECT` and `SYSTEM` have fixed IDs `"direct"` and `"system"`. `onProfileUpdate(cb)` fires in every extension context with the new and old profiles.
 
 UI pickers share one reactive profile list (`src/components/configs/useProfileOptions.ts`) and the `ProfileOptions` dropdown items.
 
@@ -74,6 +78,15 @@ UI pickers share one reactive profile list (`src/components/configs/useProfileOp
 - **`proxyverse/`** -- Our format (`version: "2025-01"`), validated with `zod/mini`. Unknown keys are stripped (so runtime fields like `pacScript.lastFetched` never reach a file), and each profile is validated on its own: an invalid one, a reserved ID (`direct`/`system`) or a repeated ID is skipped with a warning.
 - **`switchyomega/`** -- SwitchyOmega / ZeroOmega backups (`schemaVersion` 2, `+<name>` profiles, maybe base64). Profile IDs are UUIDv5 of the name, so re-importing overwrites. An enabled attached rule list (`__ruleListOf_<switch>`) is merged into its switch profile; rule lists become static auto profiles. Conditions map to our rules only where the match is exact (`conditions.ts`): URL regexes to `regex` rules, host regexes to `domain` wildcards via `regex.ts` (only those with an exact wildcard equivalent). Anything else (time, weekday, host levels, other regexes) becomes a `disabled` rule holding the condition text, plus a warning. Wildcards never carry `+()[]{}^$|\`: Firefox's PAC `shExpMatch` treats them as regex syntax.
 
+### Cloud sync (`src/services/sync/`)
+
+Profiles and three preferences (`theme.darkmode`, `ui.language`, `ui.actionBehavior`) sync through byte.vet. Protocol: `docs/sync-protocol.md`; wire contract: `docs/sync-api.openapi.yaml`, vendored from the byte.vet webapp repo (which owns it), with types generated into `api.gen.ts` (a unit test fails when they drift).
+- **`buildEnv.ts`** -- `PROXYVERSE_ENV` at build time (`build/env.ts`): `production` (byte.vet, client `proxyverse-extension`), `northernlight` (preview server, client `proxyverse-extension-dev`), `e2e` (origin overridable at runtime via `sync.devOrigin`). Chrome dev/e2e builds carry `build/dev-extension-key.pub` as `manifest.key`, fixing the extension ID and so the OAuth redirect URI (`build/README.md`); store builds never do. `identity` is a required permission everywhere: browsers show no warning for it.
+- **`auth.ts`** -- OAuth 2.1 code + PKCE via `Host.launchWebAuthFlow`, run from the Preference page (sign-in can outlive an idle service worker). Refresh tokens are single use and reuse revokes the sign-in, so refreshes hold the `proxyverse-sync-auth` lock and store the new refresh token first.
+- **`engine.ts`** -- `SyncEngine.run()`: per-record last-writer-wins by HLC (`hlc.ts`). `state.local` (this device's version) vs `state.base` (last agreed with the server) decides what's dirty; there's no outbox, so pending changes survive service worker restarts. Remote changes are written storage first, then state. `records.ts` normalizes profiles with the export schema (no PAC script for URL profiles, upper-case color) and hashes canonical JSON. The engine takes a `SyncDevice` (storage) and an API factory, so unit tests run two devices against the mock store.
+- **`index.ts` / `background.ts`** -- the real engine and `sync:*` messages (Sync now, first-sync choice, snapshots); the background syncs at start, after sign-in, 2 s after a local change and on the `sync:poll` alarm (15 min).
+- State lives in `sync.auth`, `sync.state`, `sync.settings` (local storage, never synced). "This device only" profiles are `sync.settings.localOnly`, not a profile field. UI: `src/components/sync/` (Preference section) and the switch in `ProfileConfig.vue`.
+
 ## Critical Gotcha: `deepClone()` must use JSON round-trip
 
 `deepClone()` in `src/services/utils.ts` uses `JSON.parse(JSON.stringify(obj))`. **Do not replace with `structuredClone()`** -- Vue's reactive Proxy objects throw `DataCloneError` under `structuredClone()`. The JSON round-trip serializes through Vue's Proxy traps and produces plain objects safe for `chrome.storage`.
@@ -89,6 +102,7 @@ UI pickers share one reactive profile list (`src/components/configs/useProfileOp
 - Use `data-testid` selectors; Arco dropdowns, selects and toasts render in `<body>` (helpers in `e2e/pages/arco.ts`).
 - `sw.restart()` stops the service worker via CDP `Target.closeTarget`. PAC refresh alarms are fired with `sw.fireAlarm()`.
 - Use `freshHost()` for site hosts in tests that inspect the request log (late requests of an earlier test can land in the shared log), and `freshProxyHost()` for proxy hostnames (Chrome caches proxy credentials per proxy host for the browser's lifetime).
+- **Sync** runs against a fake byte.vet (`e2e/servers/syncStore.ts` logic, `syncApi.ts` HTTP), on loopback so it's never proxied: `servers.sync` (seed records, `failNext`, `issueTokens`, request log) and `servers.syncOrigin`. Helpers in `e2e/pages/sync.ts`: `useFakeByteVet` before a UI sign-in (Chromium's auth window works headless against it), `signInDirectly` to skip it. The same store is the fake server of the engine's unit tests.
 - Firefox smoke (`e2e/firefox/`): temporary add-ons don't get private-browsing access (required by `proxy.settings`), and WebDriver can't open `moz-extension://` URLs. The driver grants the permission and opens pages from Marionette's chrome context, which needs geckodriver ≥ 0.36 with `--allow-system-access`.
 
 ## Firefox build differences
@@ -98,6 +112,8 @@ The `vite.config.ts` `TRANSFORMER_CONFIG` rewrites `manifest.json` at build time
 - Removes `version_name`
 - Adds `browser_specific_settings.gecko` (minimum version 115, for `storage.session`)
 
+The manifest transform lives in `build/manifest.ts` (pure, unit-tested in `tests/build/`).
+
 ## Path alias
 
 `@/` maps to `src/` (configured in both `vite.config.ts` and `tsconfig.json`).
diff --git a/build/README.md b/build/README.md
new file mode 100644
index 0000000..5f927a8
--- /dev/null
+++ b/build/README.md
@@ -0,0 +1,37 @@
+# build/
+
+Build-time helpers imported by `vite.config.ts`:
+
+- `env.ts` -- the build environments chosen by `PROXYVERSE_ENV`
+  (`production`, the default; `northernlight`; `e2e`) and the sync settings
+  each one compiles in.
+- `manifest.ts` -- turns the root `manifest.json` into a build's manifest.
+
+## Dev extension key
+
+`dev-extension-key.pub` is the public half of an RSA key (base64 DER
+SubjectPublicKeyInfo). Chrome builds with `PROXYVERSE_ENV=northernlight` or
+`e2e` put it in `manifest.key`, so that unpacked builds always get the same
+extension ID, and so the same OAuth redirect URI, registered on the
+`proxyverse-extension-dev` client. **Dev only**: production builds never
+carry a key (the stores assign the ID), and the private key is not kept
+anywhere -- Chrome doesn't need it for unpacked extensions.
+
+| | |
+|---|---|
+| Chrome/Edge dev extension ID | `ohbdfegnjlfoohcaiedlpbmcacohacmg` |
+| Chrome/Edge dev redirect URI | `https://ohbdfegnjlfoohcaiedlpbmcacohacmg.chromiumapp.org/oauth` |
+| Firefox redirect URI | `https://1e603ec5914c06cbcc280eb4c99adc6034a2cdff.extensions.allizom.org/oauth` |
+
+The Chrome ID is the first 32 hex digits of SHA-256 of the DER key, with
+`0-f` mapped to `a-p`. Firefox derives its redirect URL from the add-on ID
+(`proxyverse@byte.vet`, the same in every build): the hex SHA-1 of the ID,
+under `extensions.allizom.org` (`identity.getRedirectURL()`, see
+`toolkit/components/extensions/child/ext-identity.js`).
+
+To recompute them:
+
+```sh
+base64 -d -i build/dev-extension-key.pub | shasum -a 256 | cut -c1-32 | tr 0-9a-f a-p
+printf %s proxyverse@byte.vet | shasum -a 1
+```
diff --git a/build/dev-extension-key.pub b/build/dev-extension-key.pub
new file mode 100644
index 0000000..b1b891e
--- /dev/null
+++ b/build/dev-extension-key.pub
@@ -0,0 +1 @@
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtCGr3XRCvuGwix6pIJHWaB6w7bJDoQ5PgNkg84XTEwOSExGa82atNHKCvfES2zWy+k6nmj9oHnsmcknqcb0HeDr7P9lKTArhVwlV8zD0OlJAdZ6epZz8TqNgpv/rYOSkBcuXhGeOvHM2KsWFrp2ayn8xsDDUPvu+eqAq5aetG5WfX2lPfGP7kO4GOW4+sf8QsDAi5RMiVCNOnJllJfceKPeBUTrAhZM/uoJFkEISbK8TQb42FUS2JDyuNu5wQ1Do+xYoyhEwi5QFGP+vuaNZFksT6StYrbkLbQjQQCaUGhCL8riwp7nyPdUQjo0jumsr7KXuKGY/1SwerdEDJzIaVwIDAQAB
diff --git a/build/env.ts b/build/env.ts
new file mode 100644
index 0000000..39dffa1
--- /dev/null
+++ b/build/env.ts
@@ -0,0 +1,55 @@
+// Build environments, chosen by PROXYVERSE_ENV when the extension is built.
+// They set the byte.vet origin and OAuth client the sync feature talks to
+// (read at runtime by src/services/sync/buildEnv.ts) and a few manifest
+// details (build/manifest.ts). Store builds are always "production".
+
+export type BuildEnv = "production" | "northernlight" | "e2e";
+
+/** The sync server and OAuth client a build talks to. */
+export type SyncTarget = {
+  /** The byte.vet origin serving OAuth and the sync API, no trailing slash. */
+  origin: string;
+  clientID: string;
+  /** Whether the origin may be overridden at runtime (e2e only). */
+  originOverride: boolean;
+};
+
+export const BUILD_ENVS: Record<BuildEnv, SyncTarget> = {
+  production: {
+    origin: "https://byte.vet",
+    clientID: "proxyverse-extension",
+    originOverride: false,
+  },
+  northernlight: {
+    origin: "https://northernlight.byte.vet",
+    clientID: "proxyverse-extension-dev",
+    originOverride: false,
+  },
+  e2e: {
+    // placeholder: the e2e suite sets the real origin at runtime
+    origin: "http://127.0.0.1",
+    clientID: "proxyverse-extension-dev",
+    originOverride: true,
+  },
+};
+
+/** Parse PROXYVERSE_ENV; unset or empty means "production". */
+export function parseBuildEnv(value: string | undefined): BuildEnv {
+  if (!value) return "production";
+  if (Object.hasOwn(BUILD_ENVS, value)) return value as BuildEnv;
+  throw new Error(
+    `Unknown PROXYVERSE_ENV "${value}"; expected one of: ${Object.keys(
+      BUILD_ENVS
+    ).join(", ")}`
+  );
+}
+
+/** Vite `define` entries for src/services/sync/buildEnv.ts. */
+export function syncDefines(env: BuildEnv): Record<string, string> {
+  const { origin, clientID, originOverride } = BUILD_ENVS[env];
+  return {
+    __SYNC_ORIGIN__: JSON.stringify(origin),
+    __SYNC_CLIENT_ID__: JSON.stringify(clientID),
+    __SYNC_ORIGIN_OVERRIDE__: JSON.stringify(originOverride),
+  };
+}
diff --git a/build/manifest.ts b/build/manifest.ts
new file mode 100644
index 0000000..6e8ae3e
--- /dev/null
+++ b/build/manifest.ts
@@ -0,0 +1,93 @@
+// The manifest.json of a build, from the one at the repo root. Pure, so it
+// can be unit-tested (tests/build/manifest.test.ts).
+//
+// Rolldown (Vite 8) panics on nested member expressions such as
+// `manifest.background.service_worker` while transforming the config and
+// the modules it imports, so this module only reads one level deep at a
+// time, hoisting nested objects into locals.
+
+import type { BuildEnv } from "./env.ts";
+
+export type Manifest = Record<string, unknown>;
+
+export type BuildManifestOptions = {
+  mode: "chrome" | "firefox";
+  env: BuildEnv;
+  /** The CRX version, e.g. "1.2.3" or "1.2.3-beta" (see `crxVersion`). */
+  version: string;
+  /** The built background script's file name. */
+  serviceWorker: string;
+  /**
+   * The dev public key (base64 DER), giving unpacked Chrome builds a fixed
+   * extension ID. Required for Chrome northernlight and e2e builds.
+   */
+  devKey?: string;
+};
+
+const GECKO_ID = "proxyverse@byte.vet";
+
+/** The CRX version from CRX_VER (e.g. a "v1.2.3" tag). */
+export function crxVersion(crxVer: string | undefined): string {
+  if (!crxVer) return "0.0.0-dev";
+  const ver = crxVer.startsWith("v") ? crxVer.slice(1) : crxVer;
+  return ver.slice(0, 14);
+}
+
+/** Envs whose Chrome builds carry the dev key. */
+export function needsDevKey(mode: "chrome" | "firefox", env: BuildEnv) {
+  return mode === "chrome" && env !== "production";
+}
+
+const strings = (v: unknown): string[] =>
+  Array.isArray(v) ? v.map(String) : [];
+
+export function buildManifest(
+  base: Manifest,
+  opts: BuildManifestOptions
+): Manifest {
+  const { mode, env, version, serviceWorker, devKey } = opts;
+  const manifest: Manifest = JSON.parse(JSON.stringify(base));
+  const background = { ...(manifest.background as Record<string, unknown>) };
+  let permissions = strings(manifest.permissions);
+
+  manifest.version = version.split("-", 1)[0];
+  manifest.version_name = version;
+  // the hashed file name avoids cache issues
+  if (mode === "firefox") background.scripts = [serviceWorker];
+  else background.service_worker = serviceWorker;
+
+  if (mode === "firefox") {
+    delete background.service_worker;
+
+    delete manifest.version_name;
+
+    // Firefox has a sidebar instead of Chrome's side panel
+    delete manifest.side_panel;
+    permissions = permissions.filter((p) => p !== "sidePanel");
+    manifest.sidebar_action = {
+      default_panel: "index.html#/sidebar",
+      default_icon: "mini-logo.png",
+      open_at_install: false,
+    };
+
+    manifest.browser_specific_settings = {
+      gecko: {
+        id: GECKO_ID,
+        strict_min_version: "115.0",
+      },
+    };
+  }
+
+  delete manifest.key;
+  if (needsDevKey(mode, env)) {
+    if (!devKey) {
+      throw new Error(`A ${env} Chrome build needs the dev key (devKey)`);
+    }
+    manifest.key = devKey;
+  }
+
+  manifest.background = background;
+  manifest.permissions = permissions;
+
+  return manifest;
+}
diff --git a/components.d.ts b/components.d.ts
index 22e81b5..cad447e 100644
--- a/components.d.ts
+++ b/components.d.ts
@@ -36,6 +36,9 @@ declare module 'vue' {
     ALayoutHeader: typeof import('@arco-design/web-vue')['LayoutHeader']
     ALayoutSider: typeof import('@arco-design/web-vue')['LayoutSider']
     ALink: typeof import('@arco-design/web-vue')['Link']
+    AList: typeof import('@arco-design/web-vue')['List']
+    AListItem: typeof import('@arco-design/web-vue')['ListItem']
+    AListItemMeta: typeof import('@arco-design/web-vue')['ListItemMeta']
     AMenu: typeof import('@arco-design/web-vue')['Menu']
     AMenuItem: typeof import('@arco-design/web-vue')['MenuItem']
     AModal: typeof import('@arco-design/web-vue')['Modal']
@@ -46,6 +49,7 @@ declare module 'vue' {
     ARadioGroup: typeof import('@arco-design/web-vue')['RadioGroup']
     ASelect: typeof import('@arco-design/web-vue')['Select']
     ASpace: typeof import('@arco-design/web-vue')['Space']
+    ASwitch: typeof import('@arco-design/web-vue')['Switch']
     ATable: typeof import('@arco-design/web-vue')['Table']
     ATag: typeof import('@arco-design/web-vue')['Tag']
     ATextarea: typeof import('@arco-design/web-vue')['Textarea']
@@ -66,6 +70,7 @@ declare module 'vue' {
     RouterLink: typeof import('vue-router')['RouterLink']
     RouterView: typeof import('vue-router')['RouterView']
     ScriptInput: typeof import('./src/components/configs/ScriptInput.vue')['default']
+    SyncSection: typeof import('./src/components/sync/SyncSection.vue')['default']
     ThemeSwitcher: typeof import('./src/components/controls/ThemeSwitcher.vue')['default']
   }
 }
diff --git a/docs/sync-api.openapi.yaml b/docs/sync-api.openapi.yaml
new file mode 100644
index 0000000..c802828
--- /dev/null
+++ b/docs/sync-api.openapi.yaml
@@ -0,0 +1,431 @@
+openapi: 3.1.0
+info:
+  title: Proxyverse Sync API
+  version: "1"
+  description: |
+    Settings sync for the Proxyverse browser extension, hosted by byte.vet.
+    Normative behavior: `proxyverse/docs/sync-protocol.md` (the "spec").
+    Wire types on the server: `src/lib/proxyverse/types.ts`.
+
+    Every request carries `Authorization: Bearer <access_token>` (scope
+    `sync`), `X-Proxyverse-Device` and `X-Proxyverse-Version`.
+
+    **Devices.** An unknown `X-Proxyverse-Device` is registered implicitly on
+    its first authenticated call; `PUT /devices/{deviceID}` only adds
+    metadata. A device removed with `DELETE /devices/{deviceID}` is revoked:
+    every later request from it gets `403 device_revoked`.
+
+    **Errors** are RFC 9457 problem details (`application/problem+json`) with
+    a stable `code` (spec §4.5). `429 rate_limited` and `503 unavailable`
+    carry `Retry-After`; `426 client_too_old` means the extension version is
+    below the server's minimum.
+servers:
+  - url: https://byte.vet/api/proxyverse/v1
+  - url: https://northernlight.byte.vet/api/proxyverse/v1
+    description: Preview
+security:
+  - oauth2: [sync]
+
+paths:
+  /devices:
+    get:
+      operationId: listDevices
+      summary: List the account's devices
+      parameters:
+        - $ref: "#/components/parameters/Device"
+        - $ref: "#/components/parameters/Version"
+      responses:
+        "200":
+          description: Devices, including the caller.
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/Device" }
+        default: { $ref: "#/components/responses/Problem" }
+
+  /devices/{deviceID}:
+    parameters:
+      - $ref: "#/components/parameters/DeviceID"
+      - $ref: "#/components/parameters/Device"
+      - $ref: "#/components/parameters/Version"
+    put:
+      operationId: putDevice
+      summary: Register or update a device (spec §4.1)
+      description: Idempotent upsert; also updates `lastSeen`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DeviceInput" }
+      responses:
+        "200":
+          description: The stored device.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Device" }
+        default: { $ref: "#/components/responses/Problem" }
+    delete:
+      operationId: revokeDevice
+      summary: Remove (revoke) a device
+      description: The device's future requests get `403 device_revoked`.
+      responses:
+        "204": { description: Revoked. }
+        default: { $ref: "#/components/responses/Problem" }
+
+  /changes:
+    get:
+      operationId: getChanges
+      summary: Pull changes (spec §4.2)
+      description: |
+        Every record (including tombstones) with `rev > since`, ordered by
+        `rev`. `since=0` returns the full current state. A `since` older than
+        the tombstone horizon gets `410 cursor_expired`; do a full resync.
+      parameters:
+        - $ref: "#/components/parameters/Device"
+        - $ref: "#/components/parameters/Version"
+        - name: since
+          in: query
+          required: true
+          schema: { type: integer, minimum: 0 }
+        - name: limit
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 1000, default: 500 }
+      responses:
+        "200":
+          description: A page of changes.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ChangesResult" }
+        default: { $ref: "#/components/responses/Problem" }
+
+  /records:
+    post:
+      operationId: pushRecords
+      summary: Push records (spec §4.3)
+      description: |
+        Each record is processed on its own, in order (no batch atomicity).
+        Conflicts are last-writer-wins on `hlc`; a losing record is rejected
+        as `stale` with the stored record in `current`. Per-record failures
+        never fail the request.
+
+        A record that would push the account over its quota (2,000 records /
+        8 MiB) is rejected on its own as `quota_exceeded` (spec §4.5) instead
+        of the whole request failing.
+
+        The request body is limited to 2 MiB.
+      parameters:
+        - $ref: "#/components/parameters/Device"
+        - $ref: "#/components/parameters/Version"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [records]
+              properties:
+                records:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  items: { $ref: "#/components/schemas/PushRecord" }
+      responses:
+        "200":
+          description: Per-record outcome.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PushResult" }
+        default: { $ref: "#/components/responses/Problem" }
+
+  /snapshots:
+    parameters:
+      - $ref: "#/components/parameters/Device"
+      - $ref: "#/components/parameters/Version"
+    get:
+      operationId: listSnapshots
+      summary: List snapshots (spec §4.4)
+      responses:
+        "200":
+          description: Snapshots, newest first.
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/SnapshotMeta" }
+        default: { $ref: "#/components/responses/Problem" }
+    post:
+      operationId: createSnapshot
+      summary: Create a snapshot now
+      description: >-
+        Snapshots the current live records. Send
+        `{ "reason": "before-overwrite" }` before "Upload this device" on first
+        sign-in (spec §5.7); with no body, or any other reason, the snapshot is
+        recorded as `manual`.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+                  enum: [manual, before-overwrite]
+      responses:
+        "201":
+          description: The new snapshot (`reason` = `before-overwrite` or `manual`).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/SnapshotMeta" }
+        default: { $ref: "#/components/responses/Problem" }
+
+  /snapshots/{id}:
+    parameters:
+      - $ref: "#/components/parameters/SnapshotID"
+      - $ref: "#/components/parameters/Device"
+      - $ref: "#/components/parameters/Version"
+    get:
+      operationId: getSnapshot
+      summary: Get a snapshot's records (for previewing a restore)
+      responses:
+        "200":
+          description: Snapshot contents.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [records]
+                properties:
+                  records:
+                    type: array
+                    items: { $ref: "#/components/schemas/SyncRecord" }
+        default: { $ref: "#/components/responses/Problem" }
+
+  /snapshots/{id}/restore:
+    parameters:
+      - $ref: "#/components/parameters/SnapshotID"
+      - $ref: "#/components/parameters/Device"
+      - $ref: "#/components/parameters/Version"
+    post:
+      operationId: restoreSnapshot
+      summary: Restore a snapshot (spec §6.3)
+      description: |
+        Takes a `before-restore` snapshot, then writes every record of the
+        snapshot and a tombstone for every live record absent from it, as new
+        revisions so every device pulls them as ordinary changes. All of them
+        carry the HLC `max(stored T + 1, now):0000:server` and the restoring
+        device's `deviceID`. Restore never rewinds `rev`.
+      responses:
+        "200":
+          description: Restore result.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [rev, written]
+                properties:
+                  rev:
+                    {
+                      type: integer,
+                      description: Account rev after the restore.,
+                    }
+                  written: { type: integer, description: Records written. }
+        default: { $ref: "#/components/responses/Problem" }
+
+components:
+  securitySchemes:
+    oauth2:
+      type: oauth2
+      description: Authorization code with PKCE (S256), public client.
+      flows:
+        authorizationCode:
+          authorizationUrl: https://byte.vet/api/auth/oauth2/authorize
+          tokenUrl: https://byte.vet/api/auth/oauth2/token
+          refreshUrl: https://byte.vet/api/auth/oauth2/token
+          scopes:
+            sync: Read and write Proxyverse sync data.
+
+  parameters:
+    Device:
+      name: X-Proxyverse-Device
+      in: header
+      required: true
+      description: This device's id. Unknown ids are registered implicitly.
+      schema: { type: string, format: uuid }
+    Version:
+      name: X-Proxyverse-Version
+      in: header
+      required: true
+      description: Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`.
+      schema: { type: string }
+    DeviceID:
+      name: deviceID
+      in: path
+      required: true
+      schema: { type: string, format: uuid }
+    SnapshotID:
+      name: id
+      in: path
+      required: true
+      schema: { type: string }
+
+  responses:
+    Problem:
+      description: |
+        Error (spec §4.5). 400 `invalid_request`, 401 `invalid_token`,
+        403 `device_revoked`, 404 `not_found`, 410 `cursor_expired`,
+        413 `quota_exceeded`, 426 `client_too_old`, 429 `rate_limited`,
+        503 `unavailable`.
+      headers:
+        Retry-After:
+          description: Seconds to wait; sent with 429 and 503.
+          schema: { type: integer }
+      content:
+        application/problem+json:
+          schema: { $ref: "#/components/schemas/Problem" }
+
+  schemas:
+    RecordID:
+      type: string
+      description: |
+        `profile:<profileID>` or `pref:<key>` (`theme.darkmode`,
+        `ui.language`, `ui.actionBehavior`). At most 200 UTF-8 bytes.
+        `profile:direct` and `profile:system` are reserved.
+      pattern: "^(profile:.+|pref:.+)$"
+    HLC:
+      type: string
+      description: "Hybrid logical clock `TTTTTTTTTTTTTTT:CCCC:DEVICEID` (spec §3.3); compares lexicographically."
+      pattern: "^\\d{15}:\\d{4}:[A-Za-z0-9-]{1,64}$"
+    SyncRecord:
+      type: object
+      required: [id, rev, hlc, deviceID, deleted, schema, encoding, data]
+      properties:
+        id: { $ref: "#/components/schemas/RecordID" }
+        rev: { type: integer, minimum: 1, description: Server-assigned. }
+        hlc: { $ref: "#/components/schemas/HLC" }
+        deviceID: { type: string }
+        deleted: { type: boolean }
+        schema: { type: string, examples: ["2025-01"] }
+        encoding: { type: string, examples: ["json"] }
+        data:
+          description: Payload; `null` for tombstones. Opaque when `encoding` is not `json`.
+    PushRecord:
+      type: object
+      required: [id, hlc, deleted, schema, encoding, data]
+      properties:
+        id: { $ref: "#/components/schemas/RecordID" }
+        baseRev:
+          type: integer
+          minimum: 0
+          description: Informational; the conflict decision uses only `hlc`.
+        hlc: { $ref: "#/components/schemas/HLC" }
+        deleted: { type: boolean }
+        schema:
+          type: string
+          description: Payload schema version; unknown versions are rejected (`unknown_schema`) unless `encoding` is not `json`.
+        encoding:
+          type: string
+          description: "`json` is validated; other encodings are stored opaquely (spec §3.4)."
+        data:
+          description: Payload (≤ 256 KiB as JSON); must be `null` when `deleted`.
+    RejectReason:
+      type: string
+      enum:
+        [
+          stale,
+          invalid_record,
+          reserved_id,
+          too_large,
+          clock_skew,
+          unknown_schema,
+          quota_exceeded,
+        ]
+    PushResult:
+      type: object
+      required: [accepted, rejected]
+      properties:
+        accepted:
+          type: array
+          items:
+            type: object
+            required: [id, rev]
+            properties:
+              id: { type: string }
+              rev: { type: integer }
+        rejected:
+          type: array
+          items:
+            type: object
+            required: [id, reason]
+            properties:
+              id: { type: string }
+              reason: { $ref: "#/components/schemas/RejectReason" }
+              current:
+                $ref: "#/components/schemas/SyncRecord"
+                description: The stored record; present for `stale`.
+    ChangesResult:
+      type: object
+      required: [records, cursor, hasMore]
+      properties:
+        records:
+          type: array
+          items: { $ref: "#/components/schemas/SyncRecord" }
+        cursor: { type: integer, description: Pass as `since` next time. }
+        hasMore: { type: boolean }
+    Device:
+      type: object
+      required: [id, name, browser, extVersion, createdAt, lastSeen]
+      properties:
+        id: { type: string }
+        name: { type: [string, "null"] }
+        browser: { type: [string, "null"] }
+        extVersion: { type: [string, "null"] }
+        createdAt: { type: integer, description: Unix ms. }
+        lastSeen: { type: integer, description: Unix ms. }
+    DeviceInput:
+      type: object
+      properties:
+        name: { type: string, examples: ["Chrome on macOS"] }
+        browser: { type: string, examples: ["chrome"] }
+        extVersion: { type: string, examples: ["2.3.0"] }
+    SnapshotMeta:
+      type: object
+      required: [id, createdAt, reason, rev, recordCount, createdBy]
+      properties:
+        id: { type: string }
+        createdAt: { type: integer, description: Unix ms. }
+        reason:
+          type: string
+          enum: [daily, manual, before-restore, before-overwrite]
+        rev: { type: integer }
+        recordCount: { type: integer }
+        createdBy:
+          type: string
+          description: Device id, or `server` for automatic snapshots.
+    Problem:
+      type: object
+      description: RFC 9457 problem details; extra members may appear.
+      required: [type, title, status, code]
+      properties:
+        type:
+          type: string
+          format: uri
+          examples: ["https://byte.vet/docs/proxyverse-sync#cursor_expired"]
+        title: { type: string }
+        status: { type: integer }
+        code:
+          type: string
+          enum:
+            [
+              invalid_request,
+              invalid_token,
+              device_revoked,
+              not_found,
+              cursor_expired,
+              quota_exceeded,
+              client_too_old,
+              rate_limited,
+              unavailable,
+            ]
+        detail: { type: string }
diff --git a/docs/sync-protocol.md b/docs/sync-protocol.md
new file mode 100644
index 0000000..7cd5b43
--- /dev/null
+++ b/docs/sync-protocol.md
@@ -0,0 +1,496 @@
+# Proxyverse Sync Protocol — v1 (draft)
+
+Status: design only, nothing implemented. Server: `https://byte.vet`. Client: the
+Proxyverse extension (Chrome, Edge, Firefox).
+
+## 0. Decisions (from the design interview)
+
+| Topic | Decision |
+|---|---|
+| What syncs | User profiles and preferences. The active profile does **not** sync. |
+| Per-device opt-out | A profile can be marked "this device only"; preferences have a per-device toggle. |
+| Secrets | Proxy credentials sync in the payload. Protected by TLS + server-side encryption at rest. byte.vet holds the keys (not end-to-end) and uses the data only for sync. |
+| Conflicts | Per-record last-writer-wins (LWW) ordered by a hybrid logical clock (HLC), with tombstones. |
+| Trigger | Push on local change (debounced) + pull on start, sign-in and a periodic alarm. No server push channel. |
+| Auth | byte.vet is the OAuth 2.1 authorization server. Authorization Code + PKCE through `identity.launchWebAuthFlow`. |
+| PAC URL profiles | Sync `sourceURL` and interval; each device fetches the script itself. |
+| History | Server keeps account snapshots for restore. |
+| First sign-in with data on both sides | Ask: merge, keep cloud, or upload local. |
+
+Non-goals for v1: real-time push, field-level merge inside a profile, end-to-end
+encryption (the wire format reserves room for it, see §3.4), sharing profiles
+between accounts.
+
+## 1. Concepts
+
+- **Account** — a byte.vet user. Owns one *record store*.
+- **Device** — one extension install. Identified by `deviceID`, a random UUIDv4
+  created on first sign-in and kept in `storage.local` (never synced).
+- **Record** — the unit of sync and of conflict resolution. One profile or one
+  preference key is one record.
+- **rev** — a server-assigned, account-wide, strictly increasing integer. Every
+  accepted write gets the next `rev`. A client's **cursor** is the highest `rev`
+  it has applied.
+- **HLC** — the record's logical edit time, assigned by the device that made the
+  edit. Decides which write wins.
+- **Tombstone** — a record with `deleted: true` and no data.
+
+## 2. Authentication
+
+### 2.1 Discovery
+
+`GET https://byte.vet/.well-known/oauth-authorization-server` (RFC 8414) returns
+`authorization_endpoint`, `token_endpoint`, `revocation_endpoint`,
+`userinfo_endpoint` and `scopes_supported`. The issuer is
+`https://byte.vet/api/auth`, so the endpoints are
+`/api/auth/oauth2/{authorize,token,revoke,userinfo}`. The client must not
+hard-code endpoint paths other than the discovery URL.
+
+### 2.2 Client registration
+
+The extension is a **public client** (no secret, `token_endpoint_auth_method
+none`, PKCE S256 required). Production uses `client_id` `proxyverse-extension`;
+the preview server (`northernlight.byte.vet`) uses `proxyverse-extension-dev`.
+Redirect URIs registered:
+
+| Build | Redirect URI |
+|---|---|
+| Chrome Web Store | `https://<chrome-ext-id>.chromiumapp.org/oauth` |
+| Edge Add-ons | `https://<edge-ext-id>.chromiumapp.org/oauth` |
+| Firefox AMO | `https://<firefox-hash>.extensions.allizom.org/oauth` (from `browser.identity.getRedirectURL()`) |
+| Dev builds | A fixed ID from a pinned dev key, registered on `proxyverse-extension-dev` |
+
+The server must match redirect URIs exactly.
+
+### 2.3 Sign-in flow
+
+1. Generate `code_verifier` (43–128 chars), `code_challenge = BASE64URL(SHA256(verifier))`, and a random `state`.
+2. `identity.launchWebAuthFlow({ url: authorize?response_type=code&client_id&redirect_uri&scope=openid email offline_access sync&code_challenge&code_challenge_method=S256&state, interactive: true })`. It runs from the extension page, not the service worker: signing in can take minutes, longer than an idle service worker lives.
+3. Verify `state`; `POST token_endpoint` with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier`.
+4. Response: `access_token` (opaque, 1 h), `refresh_token` (rotating, single
+   use, each rotation gives a fresh 90 days), `expires_in`, `scope`. No
+   `id_token` is issued to the public client.
+5. `GET userinfo_endpoint` with the access token gives the account `email` for the UI.
+
+Scopes: `sync` (read + write the caller's own record store and snapshots),
+`offline_access` (without it there is no refresh token), `openid email` (for
+userinfo).
+
+### 2.4 Token handling
+
+- Tokens are stored in `storage.local` under `sync.auth`. Only the background
+  service worker calls the sync API; UI pages ask it via messages.
+- Before each request, refresh if the access token expires within 60 s.
+- Refresh tokens rotate: persist the new one before using the new access token.
+  Reusing a spent refresh token (outside a short replay window) revokes the
+  whole token family, so refreshes are serialized across extension contexts
+  (Web Lock `sync-auth`). If a refresh returns `invalid_grant`, enter the
+  *signed-out (expired)* state and ask the user to sign in again. Local data
+  is kept.
+- Sign-out: `POST revocation_endpoint` form-encoded
+  `token=<refresh>&token_type_hint=refresh_token&client_id=<id>` (best
+  effort; it also revokes that token's access tokens), then delete
+  `sync.auth` and `sync.state`. Local profiles stay.
+
+### 2.5 Permissions
+
+`identity` is new, a required permission on every browser. It carries no
+permission warning, so it shows nothing at install, and an update adding it
+shouldn't disable the extension for re-approval (browsers do that only for
+permissions with a warning). Requested as an optional permission at sign-in
+instead, Chrome would show a vague "wants to access your content" prompt. API calls to
+`https://byte.vet/*` are already covered by `host_permissions: <all_urls>`.
+
+## 3. Data model
+
+### 3.1 Record
+
+```jsonc
+{
+  "id": "profile:3f2a…",        // "<kind>:<key>", see 3.2
+  "rev": 1842,                   // server-assigned, read-only for clients
+  "hlc": "001730023456789:0003:7b1e…", // see 3.3
+  "deviceID": "7b1e…",          // device that made this edit
+  "deleted": false,
+  "schema": "2025-01",          // payload schema version, see 3.5
+  "encoding": "json",           // reserved for future E2E, see 3.4
+  "data": { … }                  // payload; null when deleted
+}
+```
+
+### 3.2 Record kinds
+
+| `id` | Source in `storage.local` | Payload |
+|---|---|---|
+| `profile:<profileID>` | `profiles[profileID]` | One profile in the export format (§3.6). |
+| `pref:theme.darkmode` | `theme.darkmode` | `{ "value": <DarkMode> }` |
+| `pref:ui.language` | `ui.language` | `{ "value": "auto" \| <LanguageCode> }` |
+| `pref:ui.actionBehavior` | `ui.actionBehavior` | `{ "value": "popup" \| "sidebar" }` |
+
+Preference payloads: `theme.darkmode` `{value: 0|1|2}`, `ui.language`
+`{value: "auto" | /^[a-z]{2,3}(_[A-Z]{2})?$/}` (lenient, so a new locale needs
+no schema bump), `ui.actionBehavior` `{value: "popup"|"sidebar"}`. Any other
+`pref:` key is `invalid_record`. Tombstones must have `data: null`.
+
+Never synced: `active-profile`, `tabstats:*`, `sync.*`, and the reserved
+profiles `direct` / `system` (server rejects them). New preference keys are
+added to this table explicitly; nothing syncs by default.
+
+A record id is at most 200 bytes. `profileID` is used as-is, so profiles
+imported from SwitchyOmega (UUIDv5 of the name) converge across devices.
+
+### 3.3 Hybrid logical clock
+
+Format: `TTTTTTTTTTTTTTT:CCCC:DEVICEID`
+
+- `T` — milliseconds since epoch, zero-padded to 15 digits.
+- `C` — counter, zero-padded to 4 decimal digits.
+- `DEVICEID` — the editing device's id (tie-breaker).
+
+Strings compare lexicographically, so `a > b` is a plain string compare.
+
+Device rules (persist the last HLC in `sync.state.clock`):
+
+- **Local edit:** `T = max(now, last.T)`; `C = (T == last.T) ? last.C + 1 : 0`.
+- **Receiving a record:** `last = max(last, received.hlc)` before the next
+  local edit, so a device never issues an HLC lower than one it has seen.
+
+Server rule: the HLC must match `^\d{15}:\d{4}:[A-Za-z0-9-]{1,64}$`; reject a
+write whose `T` is more than **5 min ahead** of server time (`clock_skew`). This keeps one device with a broken clock from winning
+every conflict forever. The client then shows "check your system clock".
+
+Why HLC rather than arrival order: a device that edits offline for a week and
+then reconnects would otherwise overwrite newer edits made elsewhere.
+
+### 3.4 Encryption
+
+Payloads travel in plaintext JSON over TLS 1.2+. byte.vet encrypts records
+and snapshots at rest with a per-account data key wrapped by a KMS key
+(envelope encryption), and must never log `data`. Since byte.vet holds the
+keys, this is not end-to-end encryption: the data is decrypted only to serve
+sync requests. The sign-in screen says profiles sync with their credentials,
+stored encrypted and used only for sync.
+
+`encoding` is always `"json"` in v1. A future `"e2e-v1"` would put ciphertext in
+`data`; servers must store unknown encodings opaquely and skip validation, and
+v1 clients treat records with an unknown encoding as read-only (§3.5).
+
+### 3.5 Schema versioning
+
+`schema` is the Proxyverse config format version (`FORMAT_VERSION`, today
+`"2025-01"`). Any change to the profile shape, even an additive field, bumps
+it, because the client's zod schema strips unknown keys and an older client
+would silently drop new fields on save.
+
+A client that receives a record with a schema or encoding it doesn't know:
+
+- keeps the raw record in `sync.state` but does not apply it locally;
+- never pushes over it (its local copy is stale by definition);
+- shows "a newer Proxyverse version synced data this version can't read".
+
+The server validates `data` against the schema version it names (a vendored
+copy of the client's zod `ProxyProfile`; stored data is the parsed result, so
+unknown keys are stripped as on the client), checks that `data.profileID`
+equals the id suffix, and rejects
+invalid payloads (`invalid_record`) and schema versions it doesn't know
+(`unknown_schema`). So the server must be upgraded before a client that
+writes a new schema ships.
+
+### 3.6 Profile payload normalization
+
+Before hashing or pushing, a profile goes through the same zod `ProxyProfile`
+schema as export (`src/services/config/proxyverse/schema.ts`), which drops
+runtime fields such as `pacScript.lastFetched` and `pacScript.lastError`. Then:
+
+- If `pacScript.sourceURL` is set, drop `pacScript.data`. The receiving device
+  keeps its own fetched `data` when `sourceURL` is unchanged, and fetches
+  immediately otherwise (`pacFetcher.ts`).
+- Inline PAC scripts (no `sourceURL`) keep `data`.
+- Colors are upper-cased (matches the profile editor's normalization).
+
+The content hash is SHA-256 of the canonical JSON (sorted keys, no whitespace)
+of the normalized payload. It is used to detect real local changes and to
+de-duplicate identical records.
+
+### 3.7 Limits
+
+| Limit | Value |
+|---|---|
+| Record payload | 256 KiB |
+| Records per account (incl. tombstones) | 2,000 |
+| Account total | 8 MiB |
+| Records per push request | 100 |
+| Request body | 2 MiB |
+
+## 4. Sync API
+
+Base: `https://byte.vet/api/proxyverse/v1` (all paths below are relative to it, e.g. `GET /api/proxyverse/v1/changes`). JSON in and out. Every request sends
+`Authorization: Bearer <access_token>`, `X-Proxyverse-Device: <deviceID>` and
+`X-Proxyverse-Version: <extension version>`; both headers are required and
+`deviceID` must be a UUID. An unknown device is registered implicitly on its
+first authenticated call. Errors use RFC 9457 problem details
+(`application/problem+json`, members `type`, `title`, `status`, `code`,
+`detail`) with a stable `code` field.
+
+The machine-readable contract is `docs/sync-api.openapi.yaml`, vendored from
+the byte.vet webapp repo, which owns it.
+
+### 4.1 Register device — `PUT /devices/{deviceID}`
+
+Body `{ "name": "Chrome on macOS", "browser": "chrome", "extVersion": "2.3.0" }`
+(each optional, ≤ 200 chars; omitted fields keep their stored value).
+Idempotent; also updates `lastSeen`. Optional, since any call registers the
+device, but it gives the device a name. `GET /devices` lists them; `DELETE
+/devices/{id}` removes one (its future requests get `device_revoked`).
+
+### 4.2 Pull changes — `GET /changes?since=<rev>&limit=<n>`
+
+Returns every record (including tombstones) with `rev > since`, ordered by
+`rev`. `limit` defaults to 500, maximum 1000. With no records, `cursor` is
+`max(since, current rev)`.
+
+```jsonc
+{ "records": [ /* Record */ ], "cursor": 1850, "hasMore": false }
+```
+
+`since=0` returns the full current state. If `since` is older than the
+tombstone horizon (§6), the server answers `410 cursor_expired`; the client
+then does a full resync (§5.5).
+
+### 4.3 Push — `POST /records`
+
+```jsonc
+{ "records": [
+  { "id": "profile:3f2a…", "baseRev": 1842, "hlc": "…", "deleted": false,
+    "schema": "2025-01", "encoding": "json", "data": { … } }
+] }
+```
+
+Each record is processed on its own (no batch atomicity), in order:
+
+1. Validate (§3.5, §3.7, reserved ids, `clock_skew`). Failure → `rejected` with that reason.
+2. If no stored record, or `incoming.hlc > stored.hlc` → store, assign next `rev` → `accepted`.
+3. If `incoming.hlc == stored.hlc` → already applied (retry) → `accepted` with the stored `rev`.
+4. Otherwise → `rejected` with reason `stale` and the stored record in `current`.
+
+`baseRev` is informational (diagnostics, "edited a stale copy" telemetry); the
+LWW decision uses only the HLC, so the server decides the same way no matter
+which device pushes first.
+
+```jsonc
+{ "accepted": [ { "id": "profile:3f2a…", "rev": 1851 } ],
+  "rejected": [ { "id": "pref:ui.language", "reason": "stale", "current": { /* Record */ } } ] }
+```
+
+### 4.4 Snapshots
+
+- `GET /snapshots` → a bare array `[{ "id", "createdAt", "reason", "rev", "recordCount", "createdBy" }]`, newest first.
+- `GET /snapshots/{id}` → `{ "records": [ /* Record */ ] }` (for previewing a restore)
+- `POST /snapshots` → `201`, create one now. Optional body `{ "reason": "before-overwrite" }`; any other body records `manual`.
+- `POST /snapshots/{id}/restore` → `{ "rev", "written" }`, see §6.
+
+### 4.5 Errors
+
+| HTTP | `code` | Client action |
+|---|---|---|
+| 400 | `invalid_request` | Bug; log, don't retry. |
+| 401 | `invalid_token` | Refresh once, retry; then signed-out (expired). |
+| 403 | `invalid_token` | Token lacks scope `sync` or belongs to another client. Refreshing won't help: signed-out (expired). |
+| 403 | `device_revoked` | Sign out locally. |
+| 410 | `cursor_expired` | Full resync (§5.5). |
+| 413 | `quota_exceeded` | Stop pushing; show quota message. |
+| 426 | `client_too_old` | Stop syncing; ask the user to update. |
+| 404 | `not_found` | Unknown snapshot or device; show an error. |
+| 429 / 503 | `rate_limited` / `unavailable` | Honor `Retry-After`, else exponential backoff (30 s → 30 min, with jitter). Limit: 60 requests/min per account and per device. |
+
+Per-record rejection reasons: `stale`, `invalid_record`, `reserved_id`,
+`too_large`, `clock_skew`, `unknown_schema`, and `quota_exceeded` (a record
+that would take the account over quota is rejected on its own; the rest of the
+batch still applies).
+
+## 5. Client sync engine
+
+Runs only in the background service worker. All runs are serialized with
+`navigator.locks.request("proxyverse-sync", …)`, so a restart or two
+overlapping triggers can't interleave.
+
+### 5.1 Local state (`storage.local`, never synced)
+
+```jsonc
+"sync.auth":  { "accessToken", "refreshToken", "expiresAt", "account": { "sub", "email" }, "expired"? },
+"sync.state": {
+  "deviceID": "7b1e…",
+  "cursor": 1850,
+  "clock": "<last HLC>",
+  "base":  { "<recordID>": { "rev": 1842, "hlc": "…", "hash": "…" } }, // last state agreed with server
+  "local": { "<recordID>": { "hlc": "…", "hash": "…" } },              // current local version
+  "held":  { "<recordID>": { /* Record with unknown schema/encoding */ } },
+  "needsFirstChoice": true,               // the first sync waits for the user (§5.7)
+  "synced": true,                         // the first sync (§5.7) is done
+  "lastSync": { "at": 0, "error"?: { "code", "message"? } },
+  "failed":  { "<recordID>": { "reason", "hash" } }, // refused for good; not re-pushed until edited
+  "backoff": { "until": 0, "attempts": 1 }            // after 429/503/network errors
+},
+"sync.settings": { "syncPrefs": true, "localOnly": ["<profileID>"] }
+```
+
+Being signed in (`sync.auth` present and not `expired`) is what turns sync on;
+there is no separate on/off setting. Signing out removes the keys.
+
+A record is **dirty** when `local[id].hash != base[id].hash`. There is no
+separate outbox: after a service worker restart the dirty set is recomputed by
+comparing local storage with `local`/`base`.
+
+### 5.2 Detecting local changes
+
+On a storage change to `profiles` or a synced pref key (and on each run, to
+catch changes made while the worker was asleep):
+
+1. Normalize and hash each synced profile/pref.
+2. If the hash differs from `local[id].hash`, issue a new HLC and update `local[id]`.
+3. A profile missing from local storage that has a `local` entry becomes a
+   tombstone with a new HLC.
+4. Schedule a push 2 s later (debounced).
+
+Writes made by the engine itself (§5.4) set `local` and `base` to the applied
+hash before writing storage, so the resulting storage event finds no change and
+nothing echoes back.
+
+### 5.3 A sync run
+
+Triggers: browser start, sign-in, debounced local change, alarm `sync:poll`
+every 15 min, "Sync now" button.
+
+1. **Push** dirty records, 100 per request. For each `accepted`: `base[id] = { rev, hlc, hash }`. For each `stale`: apply `current` as a remote record (§5.4).
+2. **Pull** `GET /changes?since=cursor` until `hasMore` is false. Apply each record (§5.4). Save `cursor` after each page.
+3. Record `lastSync`.
+
+Push before pull means a change made just before a poll goes out immediately;
+correctness doesn't depend on the order, because both the server and the client
+apply the same HLC rule.
+
+### 5.4 Applying a remote record
+
+```
+clock = max(clock, r.hlc)
+if r.id is local-only (5.6) or prefs sync is off for a pref: skip
+if r.schema/encoding unknown: held[r.id] = r; skip
+if local[r.id] exists and local[r.id].hlc > r.hlc:
+    keep local (it is dirty and will win on push); base[r.id] = r; skip
+apply: write/delete the profile or pref; local[r.id] = base[r.id] = { r.hlc, hash(r.data) }
+```
+
+All profile changes from one run are written in a **single** `profiles`
+storage write. The existing `refreshProxyOnProfileUpdate` listener then
+re-applies the proxy if the active profile or anything it routes to changed;
+the sync engine needs no proxy logic of its own.
+
+If a remote tombstone deletes the **active** profile, the device switches to
+`direct` and shows a notice, the same as a local delete. Applying
+`pref:ui.language` reloads open pages, as a local change does.
+
+### 5.5 Full resync
+
+Used after `cursor_expired`, and as the core of first sign-in. Pull
+`GET /changes?since=0` into memory, then for each record id in the union of
+remote and local:
+
+- same hash on both sides → mark in sync, no write;
+- only local, with a `base` entry, not dirty → it was synced before and has
+  since been deleted elsewhere (tombstone already purged) → delete locally;
+- only local otherwise (never synced, or edited since) → push it;
+- otherwise resolve by HLC (§5.4). A local profile with no `local` entry yet
+  gets a fresh HLC, so it counts as the newest edit.
+
+### 5.6 Per-device opt-out
+
+- `sync.settings.localOnly` lists profile ids this device neither pushes nor
+  applies. The list itself never syncs.
+- Marking a synced profile local-only *detaches* it: the cloud copy and other
+  devices are untouched. The dialog offers "also remove it from the cloud",
+  which pushes a tombstone and keeps the local copy.
+- Unmarking it treats the profile as a new local edit (fresh HLC), so this
+  device's version wins.
+- References: an auto-switch profile that syncs may point (rule or default) at
+  a local-only profile. Other devices don't have it; the proxy engine already
+  skips missing profiles with a warning (`profile2config.ts`). The UI warns when
+  marking a profile local-only that a synced profile references, and shows
+  "missing profile" for such rules on other devices.
+- `syncPrefs: false` turns off all `pref:*` records on this device, both ways.
+
+### 5.7 First sign-in
+
+After token exchange and device registration, pull the full state. If the
+account has no live records, or the device has no user profiles and default
+prefs, merge silently. Otherwise ask:
+
+| Choice | Effect |
+|---|---|
+| **Merge** (default) | Full resync (§5.5). Local edits win same-id conflicts. |
+| **Use cloud data** | The client offers a local backup (export-format JSON download), then replaces local profiles and synced prefs with the cloud state. |
+| **Upload this device** | Client calls `POST /snapshots` (`reason: "before-overwrite"`), then pushes all local records with fresh HLCs and tombstones every cloud record absent locally. |
+
+## 6. Server behavior
+
+### 6.1 Storage
+
+Per account: the record table (`id → Record`), a `rev` sequence, a snapshot
+list and a device list. Writes to one account are serialized (one row lock or
+one Durable Object per account), which makes the `rev` sequence gap-free and
+monotonic.
+
+### 6.2 Tombstones
+
+Kept for **90 days** after deletion, then purged. `changes?since=X` returns
+`410 cursor_expired` when `X` is lower than the highest purged `rev`. A device
+offline for longer than that does a full resync, which removes profiles it had
+synced before but that are gone from the cloud (§5.5). Only a profile that was
+*edited* on that offline device comes back; that is the intended LWW outcome.
+
+### 6.3 Snapshots
+
+A snapshot is a copy of all live records at a `rev`. The server creates one:
+
+- at most once per day, before the first write of the day;
+- before a restore, and when a client asks (`POST /snapshots`).
+
+The daily snapshot is taken before the first write of a UTC day, and only if
+live records exist. Retention: all snapshots from the last 30 days, at least the
+10 most recent.
+
+**Restore** first takes a `before-restore` snapshot, then writes every record
+of the snapshot, and a tombstone for every live record absent from it, as new
+writes with server-issued HLC `max(max stored T + 1, now) : 0000 : server`
+and the restoring device's `deviceID`. They get new `rev`s, so every
+device picks them up through the normal pull. Restore never rewinds `rev`.
+
+### 6.4 Security
+
+- TLS 1.2+ only; HSTS on `byte.vet`.
+- Envelope encryption at rest per account; `data` is never logged or included
+  in error reports.
+- Access tokens are bound to `client_id` and scope `sync`; a token only reaches
+  its own account's records.
+- Rate limit per account and per device (suggested: 60 requests/min).
+- Account deletion deletes records, snapshots and devices.
+
+## 7. Extension integration points
+
+| Area | Change |
+|---|---|
+| `src/adapters/` | `launchWebAuthFlow`, `getRedirectURL`, optional permission request. |
+| `src/services/sync/` (new) | HLC, normalization + hash, API client, engine, state. |
+| `src/background.ts` | Start engine; storage listeners; `sync:poll` alarm; message handlers for the UI. |
+| Preference page | Sign in/out, status, "Sync now", sync prefs toggle, snapshots and restore. |
+| Profile editor | "This device only" switch, with the reference warning. |
+| `manifest.json` | `identity` in `permissions`. |
+
+## 8. Open questions
+
+1. Account deletion and data export from byte.vet: is that in the website's
+   scope or does the extension need a button?
+2. Should restore preview diff against the device's local state, or just list
+   profile names?
+3. Do we need a kill switch (server flag in `/devices` response) to pause sync
+   for all clients during an incident?
+4. Quotas in §3.7 are guesses; check against real user exports.
diff --git a/e2e/firefox/smoke.e2e.ts b/e2e/firefox/smoke.e2e.ts
index ce243dc..580d199 100644
--- a/e2e/firefox/smoke.e2e.ts
+++ b/e2e/firefox/smoke.e2e.ts
@@ -11,6 +11,7 @@ import {
   standardProfiles,
 } from "../data/profiles";
 import { launchFirefox, type Firefox } from "./driver";
+import { signedInStorage } from "../pages/sync";
 
 // hosts reached without a proxy resolve to the direct server
 const DIRECT_HOSTS = ["a.test", "b.test", "direct.test", "auth.test", "fallback.test"];
@@ -160,4 +161,36 @@ test.describe("firefox smoke", () => {
 
     await setLanguage("auto");
   });
+  // last: it leaves the extension signed in to sync
+  test("syncs profiles with the fake byte.vet", async () => {
+    const { proxyA, proxyB } = standardProfiles(servers);
+    const local = (items: Record<string, unknown>) =>
+      ff.driver.executeAsyncScript(
+        `const [items, done] = arguments;
+        browser.storage.local.set(items).then(() => done(), (e) => done(String(e)));`,
+        items
+      );
+
+    await ff.openExtensionPage("/preference");
+    await ff.setProfiles([proxyA]);
+    // a completed sign-in: the Firefox auth window can't be driven here
+    await local(signedInStorage(servers));
+    await expect
+      .poll(() => servers.sync.get("profile:proxyA")?.data, { timeout: 15_000 })
+      .toMatchObject({ profileID: "proxyA" });
+
+    servers.sync.seed([{ id: "profile:proxyB", data: proxyB, deviceID: "other-device" }]);
+    await ff.driver.navigate().refresh();
+    await (await ff.byTestId("pref-sync-now")).click();
+    await expect
+      .poll(
+        () =>
+          ff.driver.executeAsyncScript(
+            `const [done] = arguments;
+            browser.storage.local.get("profiles").then((r) => done(Object.keys(r.profiles ?? {}).sort()));`
+          ),
+        { timeout: 15_000 }
+      )
+      .toEqual(["proxyA", "proxyB"]);
+  });
 });
diff --git a/e2e/global-setup.ts b/e2e/global-setup.ts
index 008c824..9f5849e 100644
--- a/e2e/global-setup.ts
+++ b/e2e/global-setup.ts
@@ -2,7 +2,10 @@ import { execSync } from "node:child_process";
 import path from "node:path";
 
 const root = path.resolve(import.meta.dirname, "..");
-const run = (cmd: string) => execSync(cmd, { cwd: root, stdio: "inherit" });
+// e2e builds: sync origin overridable at runtime
+const env = { ...process.env, PROXYVERSE_ENV: "e2e" };
+const run = (cmd: string) =>
+  execSync(cmd, { cwd: root, stdio: "inherit", env });
 
 /**
  * Build the extension before the suite runs: for both browsers, or only the
diff --git a/e2e/live/global-setup.ts b/e2e/live/global-setup.ts
new file mode 100644
index 0000000..c89d742
--- /dev/null
+++ b/e2e/live/global-setup.ts
@@ -0,0 +1,17 @@
+import { execSync } from "node:child_process";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "../..");
+
+/** A Chrome build for northernlight, with the dev key's fixed extension ID. */
+export default function globalSetup() {
+  if (process.env.E2E_SKIP_BUILD) return;
+  execSync(
+    "npx vite build --outDir .e2e-build/live-chrome --emptyOutDir --logLevel warn",
+    {
+      cwd: root,
+      stdio: "inherit",
+      env: { ...process.env, PROXYVERSE_ENV: "northernlight" },
+    }
+  );
+}
diff --git a/e2e/live/playwright.config.ts b/e2e/live/playwright.config.ts
new file mode 100644
index 0000000..a4824e1
--- /dev/null
+++ b/e2e/live/playwright.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from "@playwright/test";
+
+// The live sync smoke against northernlight.byte.vet, run by hand:
+// `npm run test:e2e:live`. It needs a person to sign in, so it is never part
+// of `npm run test:e2e` or CI.
+export default defineConfig({
+  testMatch: "**/*.live.ts",
+  globalSetup: "./global-setup.ts",
+  outputDir: "../../test-results/live",
+  // signing in by hand, twice, takes a while
+  timeout: 15 * 60_000,
+  expect: { timeout: 30_000 },
+  workers: 1,
+  reporter: [["list"]],
+});
diff --git a/e2e/live/sync.live.ts b/e2e/live/sync.live.ts
new file mode 100644
index 0000000..4bd18df
--- /dev/null
+++ b/e2e/live/sync.live.ts
@@ -0,0 +1,114 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { chromium, expect, test, type BrowserContext, type Page } from "@playwright/test";
+import type { ProfilesStorage, ProxyProfile } from "@/services/profile";
+import { ServiceWorker } from "../fixtures/sw";
+import { SyncSection } from "../pages/sync";
+
+// Two browsers with separate profiles act as two devices syncing through
+// northernlight.byte.vet. Each opens the Preference page and clicks "Sign
+// in"; you finish the sign-in (GitHub/Google, consent) in its window.
+
+const BUILD = path.resolve(import.meta.dirname, "../../.e2e-build/live-chrome");
+// the dev key's extension ID (build/README.md)
+const EXTENSION_ID = "ohbdfegnjlfoohcaiedlpbmcacohacmg";
+const ORIGIN = `chrome-extension://${EXTENSION_ID}`;
+const SIGN_IN_TIMEOUT = 5 * 60_000;
+
+type Device = {
+  name: string;
+  context: BrowserContext;
+  dir: string;
+  page: Page;
+  sw: ServiceWorker;
+};
+
+async function launch(name: string): Promise<Device> {
+  const dir = mkdtempSync(path.join(os.tmpdir(), `proxyverse-live-${name}-`));
+  const context = await chromium.launchPersistentContext(dir, {
+    channel: "chromium",
+    headless: false,
+    args: [`--disable-extensions-except=${BUILD}`, `--load-extension=${BUILD}`],
+  });
+  const page = await context.newPage();
+  await page.goto(`${ORIGIN}/index.html#/preference`);
+  return { name, context, dir, page, sw: new ServiceWorker(context, EXTENSION_ID) };
+}
+
+const profilesOf = (device: Device) => device.sw.getProfiles();
+const setProfiles = (device: Device, profiles: ProfilesStorage) =>
+  device.sw.setProfiles(profiles);
+
+async function signIn(device: Device) {
+  const { page } = device;
+  await page.getByTestId("pref-sync-signin").click();
+  console.log(`[${device.name}] Finish signing in to northernlight in the window that opened.`);
+  await expect(page.getByTestId("pref-sync-account")).toBeVisible({ timeout: SIGN_IN_TIMEOUT });
+
+  // an account with data from an earlier run asks how to combine: merge
+  const choice = page.getByTestId("pref-sync-choice-merge");
+  await page.waitForTimeout(3000);
+  if (await choice.isVisible()) await choice.click();
+  await expect(page.getByTestId("pref-sync-status")).toContainText("Last synced", {
+    timeout: 60_000,
+  });
+}
+
+/** Sync `device` until `check` holds for its profiles. */
+async function syncUntil(device: Device, check: (p: ProfilesStorage) => boolean) {
+  await expect
+    .poll(
+      async () => {
+        await device.page.getByTestId("pref-sync-now").click();
+        await device.page.waitForTimeout(1500);
+        return check(await profilesOf(device));
+      },
+      { timeout: 60_000, intervals: [1000, 3000, 5000] }
+    )
+    .toBe(true);
+}
+
+test("two devices sync through northernlight", async () => {
+  const a = await launch("A");
+  const b = await launch("B");
+  try {
+    await signIn(a);
+    await signIn(b);
+
+    const id = `live-${Date.now()}`;
+    const profile: ProxyProfile = {
+      profileID: id,
+      profileName: "Live smoke",
+      color: "#3370FF",
+      proxyType: "proxy",
+      proxyRules: {
+        default: { scheme: "http", host: "10.0.0.1", port: 3128 },
+        bypassList: [],
+      },
+    };
+
+    // created on A, shows up on B
+    await setProfiles(a, { ...(await profilesOf(a)), [id]: profile });
+    await syncUntil(b, (p) => p[id]?.profileName === "Live smoke");
+
+    // renamed on B, shows up on A
+    const onB = await profilesOf(b);
+    await setProfiles(b, { ...onB, [id]: { ...onB[id], profileName: "Live smoke, renamed" } });
+    await syncUntil(a, (p) => p[id]?.profileName === "Live smoke, renamed");
+
+    // deleted on A, gone from B
+    const onA = await profilesOf(a);
+    delete onA[id];
+    await setProfiles(a, onA);
+    await syncUntil(b, (p) => !(id in p));
+  } finally {
+    for (const d of [a, b]) {
+      // sign out: revokes the tokens of this run
+      await new SyncSection(d.page).confirm("pref-sync-signout").catch(() => undefined);
+      await d.page.waitForTimeout(1000);
+      await d.context.close();
+      rmSync(d.dir, { recursive: true, force: true });
+    }
+  }
+});
diff --git a/e2e/pages/arco.ts b/e2e/pages/arco.ts
index cd9cb6c..83c4013 100644
--- a/e2e/pages/arco.ts
+++ b/e2e/pages/arco.ts
@@ -57,6 +57,11 @@ export function toast(page: Page, text: string | RegExp) {
     .first();
 }
 
+/** The confirm button of the open popconfirm (rendered in `<body>`). */
+export function popconfirmOK(page: Page) {
+  return page.locator(".arco-popconfirm:visible .arco-btn-primary");
+}
+
 /** Fill an Arco input (the testid sits on the wrapper). */
 export async function fillInput(wrapper: Locator, value: string) {
   const input = wrapper.locator("input, textarea").first();
diff --git a/e2e/pages/preference.ts b/e2e/pages/preference.ts
index 0e17189..7b3207c 100644
--- a/e2e/pages/preference.ts
+++ b/e2e/pages/preference.ts
@@ -1,5 +1,6 @@
 import { expect, type Page } from "@playwright/test";
 import type { FilePayload } from "../data/configFiles";
+import { popconfirmOK } from "./arco";
 
 /** The Preference page (import / export) of the config page. */
 export class Preference {
@@ -20,7 +21,7 @@ export class Preference {
   async import(file: FilePayload) {
     await this.page.getByTestId("import-profiles").click();
     const chooser = this.page.waitForEvent("filechooser");
-    await this.page.locator(".arco-popconfirm:visible .arco-btn-primary").click();
+    await popconfirmOK(this.page).click();
     await (await chooser).setFiles(file);
   }
 
diff --git a/e2e/pages/sync.ts b/e2e/pages/sync.ts
new file mode 100644
index 0000000..6b60721
--- /dev/null
+++ b/e2e/pages/sync.ts
@@ -0,0 +1,83 @@
+import { expect, type Page } from "@playwright/test";
+import type { ProxyProfile } from "@/services/profile";
+import type { SyncState } from "@/services/sync/state";
+import type { Servers } from "../servers";
+import type { ServiceWorker } from "../fixtures/sw";
+import { popconfirmOK } from "./arco";
+
+/** The OAuth client e2e builds sign in as. */
+export const CLIENT_ID = "proxyverse-extension-dev";
+
+/**
+ * Storage items of a completed sign-in with the fake byte.vet: its origin
+ * and fresh tokens. For drivers that write storage themselves.
+ */
+export function signedInStorage(servers: Servers) {
+  const tokens = servers.sync.issueTokens(undefined, CLIENT_ID);
+  return {
+    "sync.devOrigin": servers.syncOrigin,
+    "sync.auth": {
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresAt: Date.now() + tokens.expires_in * 1000,
+      account: servers.sync.user,
+    },
+  };
+}
+
+/** Point the extension at the fake byte.vet (e2e builds only). */
+export async function useFakeByteVet(sw: ServiceWorker, servers: Servers) {
+  await sw.eval(
+    (origin) => chrome.storage.local.set({ "sync.devOrigin": origin }),
+    servers.syncOrigin
+  );
+}
+
+/**
+ * Sign in without the browser's auth window: store tokens the fake server
+ * issued, as a completed sign-in does. The background starts syncing.
+ */
+export async function signInDirectly(sw: ServiceWorker, servers: Servers) {
+  await sw.eval((items) => chrome.storage.local.set(items), signedInStorage(servers));
+}
+
+/** Wait until this device has finished a sync run without error. */
+export async function expectSynced(sw: ServiceWorker, since = 0) {
+  await expect
+    .poll(async () => {
+      const state = (await sw.getLocal("sync.state")) as SyncState | undefined;
+      return state?.lastSync && state.lastSync.at > since && !state.lastSync.error
+        ? "synced"
+        : JSON.stringify(state?.lastSync ?? (state?.needsFirstChoice ? "needs first choice" : "not yet"));
+    }, { timeout: 15_000 })
+    .toBe("synced");
+}
+
+/** A record of `profile` as another device would have pushed it. */
+export function remoteProfile(profile: ProxyProfile, deleted = false) {
+  return {
+    id: `profile:${profile.profileID}`,
+    deleted,
+    data: deleted ? null : profile,
+    deviceID: "other-device",
+  };
+}
+
+/** The Sync section of the Preference page. */
+export class SyncSection {
+  constructor(readonly page: Page) {}
+
+  byId(id: string) {
+    return this.page.getByTestId(id);
+  }
+
+  async syncNow() {
+    await this.byId("pref-sync-now").click();
+  }
+
+  /** Click a button guarded by a popconfirm, and confirm. */
+  async confirm(testID: string) {
+    await this.byId(testID).click();
+    await popconfirmOK(this.page).click();
+  }
+}
diff --git a/e2e/servers/index.ts b/e2e/servers/index.ts
index 42938d2..2e8ebcc 100644
--- a/e2e/servers/index.ts
+++ b/e2e/servers/index.ts
@@ -4,9 +4,11 @@ import os from "node:os";
 import { createHttpProxy } from "./httpProxy";
 import { ContentStore, RequestLog, respond } from "./routeServer";
 import { createSocks5Server } from "./socks5";
+import { createSyncServer } from "./syncApi";
 
 export { ContentStore, RequestLog } from "./routeServer";
 export type { LogEntry, Route } from "./routeServer";
+export { SyncStore } from "./syncStore";
 
 export const AUTH = { username: "e2e-user", password: "e2e-pass" };
 
@@ -40,6 +42,8 @@ export type Servers = Awaited<ReturnType<typeof startServers>>;
  * - `proxyA`, `proxyB`: HTTP proxies
  * - `auth`: HTTP proxy requiring Basic auth (`AUTH`)
  * - `socks`: SOCKS5 proxy
+ * - `sync`: fake byte.vet (OAuth + sync API), on loopback so Chrome never
+ *   proxies it, whatever profile a test activates
  */
 export async function startServers() {
   const log = new RequestLog();
@@ -52,7 +56,8 @@ export async function startServers() {
   const proxyB = createHttpProxy("proxyB", log, store);
   const auth = createHttpProxy("auth", log, store, AUTH);
   const socks = createSocks5Server("socks", log, store);
-  const all: net.Server[] = [direct, proxyA, proxyB, auth, socks];
+  const sync = createSyncServer();
+  const all: net.Server[] = [direct, proxyA, proxyB, auth, socks, sync.server];
 
   const ports = {
     // on all interfaces: fake sites (LAN IP) and loopback URLs
@@ -62,6 +67,7 @@ export async function startServers() {
     auth: await listen(auth),
     socks: await listen(socks),
     closed: await closedPort(),
+    sync: await listen(sync.server),
   };
 
   return {
@@ -72,9 +78,14 @@ export async function startServers() {
     url: (host: string, path = "/") => `http://${host}:${ports.direct}${path}`,
     /** URL served by the `direct` server on loopback, never proxied. */
     localURL: (path: string) => `http://127.0.0.1:${ports.direct}${path}`,
+    /** The fake byte.vet's state and test controls. */
+    sync: sync.store,
+    /** Origin of the fake byte.vet, e.g. for its discovery URL. */
+    syncOrigin: `http://127.0.0.1:${ports.sync}`,
     reset() {
       log.clear();
       store.clear();
+      sync.store.reset();
     },
     async close() {
       all.forEach((s) => {
diff --git a/e2e/servers/syncApi.ts b/e2e/servers/syncApi.ts
new file mode 100644
index 0000000..b61a16f
--- /dev/null
+++ b/e2e/servers/syncApi.ts
@@ -0,0 +1,44 @@
+import http from "node:http";
+import { SyncStore, type SyncStoreOptions } from "./syncStore";
+
+const CORS_HEADERS = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "GET, POST, PUT, DELETE, OPTIONS",
+  "access-control-allow-headers":
+    "Authorization, Content-Type, X-Proxyverse-Device, X-Proxyverse-Version",
+  "access-control-expose-headers": "Retry-After, WWW-Authenticate, Location",
+  "access-control-max-age": "600",
+};
+
+/**
+ * The fake byte.vet (OAuth + Proxyverse sync API) over HTTP, at the real
+ * paths. All logic lives in `SyncStore`; this only adapts node:http to it and
+ * adds CORS.
+ */
+export function createSyncServer(options?: SyncStoreOptions) {
+  const store = new SyncStore(options);
+  const server = http.createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => {
+      if (req.method === "OPTIONS") {
+        res.writeHead(204, CORS_HEADERS);
+        res.end();
+        return;
+      }
+      const headers: Record<string, string | undefined> = {};
+      for (const [k, v] of Object.entries(req.headers))
+        headers[k] = Array.isArray(v) ? v.join(", ") : v;
+      const body = Buffer.concat(chunks).toString("utf8");
+      const out = store.handle({
+        method: req.method ?? "GET",
+        url: `http://${req.headers.host ?? "127.0.0.1"}${req.url ?? "/"}`,
+        headers,
+        body: body || undefined,
+      });
+      res.writeHead(out.status, { ...CORS_HEADERS, ...out.headers });
+      res.end(out.body);
+    });
+  });
+  return { server, store };
+}
diff --git a/e2e/servers/syncStore.ts b/e2e/servers/syncStore.ts
new file mode 100644
index 0000000..b4e41c7
--- /dev/null
+++ b/e2e/servers/syncStore.ts
@@ -0,0 +1,1162 @@
+/// <reference types="node" />
+/**
+ * In-memory fake of byte.vet's OAuth server and Proxyverse sync API, for
+ * tests. Pure logic, no sockets: `syncApi.ts` serves it over HTTP for e2e, and
+ * unit tests use it directly or through `store.fetch` (a `fetch` drop-in).
+ *
+ * Behavior follows docs/sync-protocol.md (§2, §3, §4, §6) and the real
+ * server's wire contract (webapp docs/proxyverse-sync.openapi.yaml):
+ * webapp `src/lib/proxyverse/{api,validate}.ts` and ws-relay
+ * `src/sync/sync-store.ts`. One account, one user.
+ *
+ * Only depends on `node:crypto`, so it type-checks under both the root and
+ * the e2e tsconfig and runs in vitest.
+ */
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import type { components } from "../../src/services/sync/api.gen";
+
+// ── Wire types: the contract's, generated from docs/sync-api.openapi.yaml ──
+
+export const HLC_PATTERN = /^(\d{15}):(\d{4}):([A-Za-z0-9-]{1,64})$/;
+
+type Schemas = components["schemas"];
+export type SyncRecord = Schemas["SyncRecord"];
+export type PushRecord = Schemas["PushRecord"];
+export type RejectReason = Schemas["RejectReason"];
+export type PushResult = Schemas["PushResult"];
+export type ChangesResult = Schemas["ChangesResult"];
+export type Device = Schemas["Device"];
+export type DeviceInput = Schemas["DeviceInput"];
+export type SnapshotMeta = Schemas["SnapshotMeta"];
+export type SnapshotReason = SnapshotMeta["reason"];
+export type SyncErrorCode = Schemas["Problem"]["code"];
+
+export const SYNC_ERROR_STATUS: Record<SyncErrorCode, number> = {
+  invalid_request: 400,
+  invalid_token: 401,
+  device_revoked: 403,
+  not_found: 404,
+  cursor_expired: 410,
+  quota_exceeded: 413,
+  client_too_old: 426,
+  rate_limited: 429,
+  unavailable: 503,
+};
+
+const PROBLEM_TITLES: Record<string, string> = {
+  invalid_request: "Invalid request",
+  invalid_token: "Invalid or expired access token",
+  device_revoked: "Device revoked",
+  not_found: "Not found",
+  cursor_expired: "Cursor expired",
+  quota_exceeded: "Quota exceeded",
+  client_too_old: "Client too old",
+  rate_limited: "Rate limited",
+  unavailable: "Service unavailable",
+};
+
+const PROBLEM_TYPE_BASE = "https://byte.vet/docs/proxyverse-sync#";
+
+/** RFC 9457 problem details, as the real server sends them. */
+export interface Problem {
+  type: string;
+  title: string;
+  status: number;
+  code: string;
+  detail?: string;
+}
+
+/** A request-level error (`application/problem+json`). */
+export class SyncProblem extends Error {
+  constructor(
+    readonly code: string,
+    readonly detail?: string,
+    readonly status = SYNC_ERROR_STATUS[code as SyncErrorCode] ?? 500,
+    readonly retryAfter?: number
+  ) {
+    super(`${code}${detail ? `: ${detail}` : ""}`);
+  }
+
+  get body(): Problem {
+    return {
+      type: PROBLEM_TYPE_BASE + this.code,
+      title: PROBLEM_TITLES[this.code] ?? this.code,
+      status: this.status,
+      code: this.code,
+      ...(this.detail !== undefined ? { detail: this.detail } : {}),
+    };
+  }
+}
+
+/** An OAuth error (RFC 6749 §5.2): `{error, error_description}`. */
+export class OAuthError extends Error {
+  constructor(
+    readonly error: string,
+    readonly description?: string,
+    readonly status = error === "invalid_client" || error === "invalid_token" ? 401 : 400
+  ) {
+    super(`${error}${description ? `: ${description}` : ""}`);
+  }
+
+  get body() {
+    return {
+      error: this.error,
+      ...(this.description ? { error_description: this.description } : {}),
+    };
+  }
+}
+
+// ── Limits (spec §3.7) ─────────────────────────────────────────────────
+
+export const SYNC_LIMITS = {
+  recordPayloadBytes: 256 * 1024,
+  recordsPerAccount: 2000,
+  accountBytes: 8 * 1024 * 1024,
+  recordsPerPush: 100,
+  requestBodyBytes: 2 * 1024 * 1024,
+  recordIdBytes: 200,
+  changesDefaultLimit: 500,
+  changesMaxLimit: 1000,
+  clockSkewMs: 5 * 60 * 1000,
+} as const;
+
+export const KNOWN_SCHEMAS = new Set(["2025-01"]);
+const RESERVED_PROFILES = new Set(["direct", "system"]);
+
+export const SYNC_BASE_PATH = "/api/proxyverse/v1";
+export const OAUTH_BASE_PATH = "/api/auth/oauth2";
+export const SUPPORTED_SCOPES = ["openid", "email", "offline_access", "sync"];
+
+// ── Options ────────────────────────────────────────────────────────────
+
+export interface SyncStoreOptions {
+  /** Accepted OAuth client ids. */
+  clientIDs?: string[];
+  /** Redirect URI check; default: `https://*.chromiumapp.org/oauth` or `https://*.extensions.allizom.org/oauth`. */
+  redirectURIAllowed?: (uri: string, clientID: string) => boolean;
+  /** The account's user. */
+  user?: { sub: string; email: string };
+  accessTokenTtlMs?: number;
+  refreshTokenTtlMs?: number;
+  /** Per-account quotas (records incl. tombstones, and payload bytes). */
+  maxRecords?: number;
+  maxBytes?: number;
+  /** `X-Proxyverse-Version` below this gets 426 `client_too_old`. */
+  minVersion?: string;
+}
+
+export const DEFAULT_CLIENT_IDS = [
+  "proxyverse-extension",
+  "proxyverse-extension-dev",
+];
+
+const DEFAULT_REDIRECT_RE =
+  /^https:\/\/[a-z0-9-]+(\.[a-z0-9-]+)*\.(chromiumapp\.org|extensions\.allizom\.org)\/oauth$/i;
+
+const DEFAULTS: Required<SyncStoreOptions> = {
+  clientIDs: DEFAULT_CLIENT_IDS,
+  redirectURIAllowed: (uri) => DEFAULT_REDIRECT_RE.test(uri),
+  user: { sub: "e2e-user", email: "e2e-user@example.test" },
+  accessTokenTtlMs: 60 * 60 * 1000,
+  refreshTokenTtlMs: 90 * 24 * 60 * 60 * 1000,
+  maxRecords: SYNC_LIMITS.recordsPerAccount,
+  maxBytes: SYNC_LIMITS.accountBytes,
+  minVersion: "",
+};
+
+// ── Test-control types ─────────────────────────────────────────────────
+
+export interface Failure {
+  status: number;
+  code: string;
+  retryAfter?: number;
+  /** Only requests whose pathname contains this (e.g. "/records"); any request if omitted. */
+  path?: string;
+  /** Only this method, e.g. "POST". */
+  method?: string;
+  detail?: string;
+}
+
+export interface RequestLogEntry {
+  method: string;
+  path: string;
+  query: Record<string, string>;
+  status: number;
+  /** Problem `code` or OAuth `error`, for error responses. */
+  code?: string;
+  device?: string;
+  version?: string;
+  /** Parsed JSON or form body, if any. */
+  body?: unknown;
+  time: number;
+}
+
+/** A record for `seed()`; missing fields get defaults. */
+export type SeedRecord = Partial<Omit<SyncRecord, "rev">> & { id: string };
+
+/** A request as `handle()` sees it. Header names are lower-case. */
+export interface SyncRequest {
+  method: string;
+  /** Absolute URL. */
+  url: string;
+  headers: Record<string, string | undefined>;
+  body?: string;
+}
+
+export interface SyncResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+const utf8Length = (s: string) => Buffer.byteLength(s, "utf8");
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export const isUUID = (v: unknown): v is string =>
+  typeof v === "string" && UUID_RE.test(v);
+
+export function formatHlc(t: number, c: number, deviceID: string): string {
+  return `${String(t).padStart(15, "0")}:${String(c).padStart(4, "0")}:${deviceID}`;
+}
+
+const hlcTime = (hlc: string) => Number(HLC_PATTERN.exec(hlc)?.[1] ?? 0);
+
+export function pkceChallenge(verifier: string): string {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+
+function compareVersions(a: string, b: string): number {
+  const pa = a.split(/[.+-]/).map((p) => Number.parseInt(p, 10) || 0);
+  const pb = b.split(/[.+-]/).map((p) => Number.parseInt(p, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+const clone = <T>(v: T): T => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+
+const PREF_VALIDATORS: Record<string, (v: unknown) => boolean> = {
+  "theme.darkmode": (v) => v === 0 || v === 1 || v === 2,
+  "ui.language": (v) =>
+    v === "auto" || (typeof v === "string" && /^[a-z]{2,3}(_[A-Z]{2})?$/.test(v)),
+  "ui.actionBehavior": (v) => v === "popup" || v === "sidebar",
+};
+
+type Validated =
+  | { ok: true; record: PushRecord }
+  | { ok: false; id: string; reason: RejectReason; detail: string };
+
+/**
+ * Per-record validation, in the real server's order (webapp
+ * `validate.ts`). `clock_skew`, `stale` and quotas need state and are decided
+ * in `push`.
+ */
+export function validatePushRecord(input: unknown): Validated {
+  const fail = (id: string, reason: RejectReason, detail: string): Validated => ({
+    ok: false,
+    id,
+    reason,
+    detail,
+  });
+  if (!isPlainObject(input)) return fail("", "invalid_record", "record must be an object");
+  const id = typeof input.id === "string" ? input.id : "";
+  if (!id) return fail("", "invalid_record", "id must be a non-empty string");
+
+  const { hlc, deleted, schema, encoding, baseRev, data } = input;
+  if (typeof hlc !== "string" || !HLC_PATTERN.test(hlc))
+    return fail(id, "invalid_record", "hlc must match TTTTTTTTTTTTTTT:CCCC:DEVICEID");
+  if (typeof deleted !== "boolean")
+    return fail(id, "invalid_record", "deleted must be a boolean");
+  if (typeof schema !== "string" || !schema)
+    return fail(id, "invalid_record", "schema must be a non-empty string");
+  if (typeof encoding !== "string" || !encoding)
+    return fail(id, "invalid_record", "encoding must be a non-empty string");
+  if (
+    baseRev !== undefined &&
+    !(typeof baseRev === "number" && Number.isSafeInteger(baseRev) && baseRev >= 0)
+  )
+    return fail(id, "invalid_record", "baseRev must be a non-negative integer");
+  if (!("data" in input) || data === undefined)
+    return fail(id, "invalid_record", "data is required (null for tombstones)");
+
+  if (utf8Length(id) > SYNC_LIMITS.recordIdBytes)
+    return fail(id, "invalid_record", `id exceeds ${SYNC_LIMITS.recordIdBytes} bytes`);
+  let kind: "profile" | "pref";
+  let key: string;
+  if (id.startsWith("profile:") && id.length > "profile:".length) {
+    kind = "profile";
+    key = id.slice("profile:".length);
+    if (RESERVED_PROFILES.has(key))
+      return fail(id, "reserved_id", `profile "${key}" is built in and never synced`);
+  } else if (id.startsWith("pref:") && id.slice(5) in PREF_VALIDATORS) {
+    kind = "pref";
+    key = id.slice(5);
+  } else {
+    return fail(id, "invalid_record", "id must be profile:<profileID> or pref:<known key>");
+  }
+
+  if (deleted && data !== null)
+    return fail(id, "invalid_record", "tombstones must have data: null");
+  if (!deleted && data === null)
+    return fail(id, "invalid_record", "data must not be null unless deleted");
+
+  const record: PushRecord = {
+    id,
+    ...(baseRev !== undefined ? { baseRev: baseRev as number } : {}),
+    hlc,
+    deleted,
+    schema,
+    encoding,
+    data,
+  };
+
+  // unknown encodings (future E2E) are stored opaquely, unvalidated (§3.4)
+  const opaque = encoding !== "json";
+  if (!opaque && !KNOWN_SCHEMAS.has(schema))
+    return fail(id, "unknown_schema", `unknown schema version "${schema}"`);
+
+  const size = utf8Length(JSON.stringify(data));
+  if (size > SYNC_LIMITS.recordPayloadBytes)
+    return fail(
+      id,
+      "too_large",
+      `payload is ${size} bytes; limit is ${SYNC_LIMITS.recordPayloadBytes}`
+    );
+
+  if (deleted || opaque) return { ok: true, record };
+
+  if (!isPlainObject(data)) return fail(id, "invalid_record", "data must be an object");
+  if (kind === "pref") {
+    if (!PREF_VALIDATORS[key](data.value))
+      return fail(id, "invalid_record", `invalid value for pref "${key}"`);
+  } else {
+    // Lighter than the real server, which parses `data` with a vendored copy
+    // of the client's zod `ProxyProfile` (and stores the parsed result, with
+    // unknown keys stripped). Here: profileID matches, proxyType is a string,
+    // and the payload is stored as sent.
+    if (typeof data.proxyType !== "string")
+      return fail(id, "invalid_record", "proxyType must be a string");
+    if (data.profileID !== key)
+      return fail(id, "invalid_record", "data.profileID does not match the record id");
+  }
+  return { ok: true, record };
+}
+
+// ── OAuth state ────────────────────────────────────────────────────────
+
+interface AuthCode {
+  clientID: string;
+  redirectURI: string;
+  challenge: string;
+  scopes: string[];
+  expiresAt: number;
+}
+
+interface TokenEntry {
+  kind: "access" | "refresh";
+  clientID: string;
+  scopes: string[];
+  family: string;
+  expiresAt: number;
+  revoked: boolean;
+  /** Refresh tokens: already exchanged once. */
+  used?: boolean;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  token_type: "Bearer";
+  expires_in: number;
+  refresh_token?: string;
+  scope: string;
+}
+
+interface StoredDevice extends Device {
+  revokedAt: number | null;
+}
+
+interface Snapshot extends SnapshotMeta {
+  records: SyncRecord[];
+  seq: number;
+}
+
+// ── The store ──────────────────────────────────────────────────────────
+
+export class SyncStore {
+  private base: Required<SyncStoreOptions>;
+  private opts!: Required<SyncStoreOptions>;
+
+  // sync state
+  private recs = new Map<string, SyncRecord>();
+  private rev = 0;
+  private purgedRev = 0;
+  private devs = new Map<string, StoredDevice>();
+  private snaps: Snapshot[] = [];
+  private snapSeq = 0;
+
+  // oauth state
+  private codes = new Map<string, AuthCode>();
+  private tokens = new Map<string, TokenEntry>();
+
+  // test controls
+  private fixedNow: number | null = null;
+  private failures: Failure[] = [];
+  /** Every request through `handle()`/`fetch`, oldest first. */
+  log: RequestLogEntry[] = [];
+
+  constructor(options: SyncStoreOptions = {}) {
+    this.base = { ...DEFAULTS, ...options };
+    this.reset();
+  }
+
+  // ── Test controls ──
+
+  /** Back to an empty account, no tokens, the constructor's options, real time. */
+  reset() {
+    this.opts = { ...this.base };
+    this.recs.clear();
+    this.rev = 0;
+    this.purgedRev = 0;
+    this.devs.clear();
+    this.snaps = [];
+    this.snapSeq = 0;
+    this.codes.clear();
+    this.tokens.clear();
+    this.fixedNow = null;
+    this.failures = [];
+    this.log = [];
+  }
+
+  /** Override options until the next `reset()`. */
+  configure(options: SyncStoreOptions) {
+    this.opts = { ...this.opts, ...options };
+  }
+
+  get user() {
+    return { ...this.opts.user };
+  }
+
+  /** Freeze the server clock at `ms`; `null` goes back to real time. */
+  setNow(ms: number | null) {
+    this.fixedNow = ms;
+  }
+
+  now(): number {
+    return this.fixedNow ?? Date.now();
+  }
+
+  /** One-shot error for the next matching request (queued; first match wins). */
+  failNext(failure: Failure) {
+    this.failures.push(failure);
+  }
+
+  /** Expire every access token issued so far (refresh tokens stay valid). */
+  expireAccessTokens() {
+    const past = this.now() - 1;
+    for (const t of this.tokens.values()) if (t.kind === "access") t.expiresAt = past;
+  }
+
+  /**
+   * Write records directly, as if pushed by another device: no validation,
+   * no LWW. Each gets the next rev. Defaults: `hlc` now (counter = position),
+   * device `seed-device`, live, schema 2025-01, encoding json.
+   */
+  seed(records: SeedRecord[]): SyncRecord[] {
+    const now = this.now();
+    return records.map((r, i) => {
+      const deviceID = r.deviceID ?? "seed-device";
+      const deleted = r.deleted ?? false;
+      const rec: SyncRecord = {
+        id: r.id,
+        rev: ++this.rev,
+        hlc: r.hlc ?? formatHlc(now, i, deviceID),
+        deviceID,
+        deleted,
+        schema: r.schema ?? "2025-01",
+        encoding: r.encoding ?? "json",
+        data: deleted ? null : clone(r.data ?? null),
+      };
+      this.recs.set(rec.id, rec);
+      return clone(rec);
+    });
+  }
+
+  /** All stored records, tombstones included, by rev. */
+  records(): SyncRecord[] {
+    return [...this.recs.values()].sort((a, b) => a.rev - b.rev).map(clone);
+  }
+
+  get(id: string): SyncRecord | undefined {
+    const r = this.recs.get(id);
+    return r && clone(r);
+  }
+
+  /** The account's current rev. */
+  currentRev() {
+    return this.rev;
+  }
+
+  /**
+   * Drop every tombstone (as the 90-day purge would) and remember the highest
+   * purged rev; `changes(since)` with 0 < since < that rev then gets 410.
+   */
+  purgeTombstones(): number {
+    let max = 0;
+    for (const [id, r] of this.recs) {
+      if (!r.deleted) continue;
+      max = Math.max(max, r.rev);
+      this.recs.delete(id);
+    }
+    this.purgedRev = Math.max(this.purgedRev, max);
+    return this.purgedRev;
+  }
+
+  /** Logged requests whose path contains `path`. */
+  requests(path?: string, method?: string): RequestLogEntry[] {
+    return this.log.filter(
+      (e) => (!path || e.path.includes(path)) && (!method || e.method === method)
+    );
+  }
+
+  // ── OAuth ──
+
+  /**
+   * Authorization endpoint; auto-approves. Returns the redirect URL (with
+   * `code` and `state`, or `error`). Throws `OAuthError` when the client or
+   * redirect URI is invalid (nothing to redirect to safely).
+   */
+  authorize(params: {
+    client_id?: string | null;
+    redirect_uri?: string | null;
+    code_challenge?: string | null;
+    code_challenge_method?: string | null;
+    state?: string | null;
+    scope?: string | null;
+    response_type?: string | null;
+  }): string {
+    const clientID = params.client_id ?? "";
+    const redirectURI = params.redirect_uri ?? "";
+    if (!this.opts.clientIDs.includes(clientID))
+      throw new OAuthError("invalid_client", "unknown client_id");
+    if (!this.opts.redirectURIAllowed(redirectURI, clientID))
+      throw new OAuthError("invalid_request", "redirect_uri is not registered");
+
+    const target = new URL(redirectURI);
+    const redirectError = (error: string, description: string) => {
+      target.searchParams.set("error", error);
+      target.searchParams.set("error_description", description);
+      if (params.state) target.searchParams.set("state", params.state);
+      return target.href;
+    };
+    if (params.response_type !== undefined && params.response_type !== null && params.response_type !== "code")
+      return redirectError("unsupported_response_type", "response_type must be code");
+    if (!params.code_challenge || params.code_challenge_method !== "S256")
+      return redirectError("invalid_request", "PKCE with S256 is required");
+
+    const scopes = (params.scope ?? "")
+      .split(/\s+/)
+      .filter((s) => SUPPORTED_SCOPES.includes(s));
+    const code = randomBytes(24).toString("base64url");
+    this.codes.set(code, {
+      clientID,
+      redirectURI,
+      challenge: params.code_challenge,
+      scopes,
+      expiresAt: this.now() + 10 * 60 * 1000,
+    });
+    target.searchParams.set("code", code);
+    if (params.state) target.searchParams.set("state", params.state);
+    return target.href;
+  }
+
+  /** Token endpoint: `authorization_code` (PKCE) and `refresh_token` grants. */
+  token(params: Record<string, string | undefined>): TokenResponse {
+    const clientID = params.client_id ?? "";
+    if (!this.opts.clientIDs.includes(clientID))
+      throw new OAuthError("invalid_client", "unknown client_id");
+
+    if (params.grant_type === "authorization_code") {
+      const code = this.codes.get(params.code ?? "");
+      if (!code) throw new OAuthError("invalid_grant", "unknown or used code");
+      this.codes.delete(params.code!); // single use, even on failure
+      if (code.expiresAt <= this.now()) throw new OAuthError("invalid_grant", "code expired");
+      if (code.clientID !== clientID)
+        throw new OAuthError("invalid_grant", "code was issued to another client");
+      if (code.redirectURI !== params.redirect_uri)
+        throw new OAuthError("invalid_grant", "redirect_uri mismatch");
+      const verifier = params.code_verifier ?? "";
+      if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier))
+        throw new OAuthError("invalid_request", "code_verifier must be 43-128 chars");
+      if (pkceChallenge(verifier) !== code.challenge)
+        throw new OAuthError("invalid_grant", "PKCE verification failed");
+      return this.issue(clientID, code.scopes, randomUUID());
+    }
+
+    if (params.grant_type === "refresh_token") {
+      const value = params.refresh_token ?? "";
+      const entry = this.tokens.get(value);
+      if (!entry || entry.kind !== "refresh")
+        throw new OAuthError("invalid_grant", "unknown refresh token");
+      if (entry.clientID !== clientID)
+        throw new OAuthError("invalid_grant", "refresh token was issued to another client");
+      if (entry.used) {
+        // reuse of a rotated token: assume theft, revoke the whole family
+        this.revokeFamily(entry.family);
+        throw new OAuthError("invalid_grant", "refresh token reused");
+      }
+      if (entry.revoked) throw new OAuthError("invalid_grant", "refresh token revoked");
+      if (entry.expiresAt <= this.now())
+        throw new OAuthError("invalid_grant", "refresh token expired");
+      entry.used = true;
+      return this.issue(clientID, entry.scopes, entry.family);
+    }
+
+    throw new OAuthError("unsupported_grant_type");
+  }
+
+  /**
+   * Issue tokens without the authorize dance (for unit tests). Scopes
+   * default to `openid email offline_access sync`.
+   */
+  issueTokens(
+    scopes = ["openid", "email", "offline_access", "sync"],
+    clientID = this.opts.clientIDs[0]
+  ): TokenResponse {
+    return this.issue(clientID, scopes, randomUUID());
+  }
+
+  private issue(clientID: string, scopes: string[], family: string): TokenResponse {
+    const now = this.now();
+    const access = `at_${randomBytes(24).toString("base64url")}`;
+    this.tokens.set(access, {
+      kind: "access",
+      clientID,
+      scopes,
+      family,
+      expiresAt: now + this.opts.accessTokenTtlMs,
+      revoked: false,
+    });
+    const res: TokenResponse = {
+      access_token: access,
+      token_type: "Bearer",
+      expires_in: Math.floor(this.opts.accessTokenTtlMs / 1000),
+      scope: scopes.join(" "),
+    };
+    if (scopes.includes("offline_access")) {
+      const refresh = `rt_${randomBytes(24).toString("base64url")}`;
+      this.tokens.set(refresh, {
+        kind: "refresh",
+        clientID,
+        scopes,
+        family,
+        expiresAt: now + this.opts.refreshTokenTtlMs,
+        revoked: false,
+      });
+      res.refresh_token = refresh;
+    }
+    return res;
+  }
+
+  private revokeFamily(family: string) {
+    for (const t of this.tokens.values()) if (t.family === family) t.revoked = true;
+  }
+
+  /**
+   * Revocation endpoint (RFC 7009): always succeeds. A refresh token also
+   * revokes its family's access tokens.
+   */
+  revoke(token: string) {
+    const entry = this.tokens.get(token);
+    if (!entry) return;
+    if (entry.kind === "refresh") this.revokeFamily(entry.family);
+    else entry.revoked = true;
+  }
+
+  /** Userinfo endpoint. Throws `OAuthError("invalid_token")` (401). */
+  userinfo(accessToken: string): { sub: string; email?: string } {
+    const entry = this.validAccessToken(accessToken);
+    if (!entry) throw new OAuthError("invalid_token", "invalid or expired access token");
+    return entry.scopes.includes("email")
+      ? { sub: this.opts.user.sub, email: this.opts.user.email }
+      : { sub: this.opts.user.sub };
+  }
+
+  private validAccessToken(token: string): TokenEntry | null {
+    const entry = this.tokens.get(token);
+    if (!entry || entry.kind !== "access" || entry.revoked) return null;
+    if (entry.expiresAt <= this.now()) return null;
+    return entry;
+  }
+
+  /**
+   * Checks a sync API bearer token as the real server does: 401 when
+   * missing/unknown/expired, 403 without scope `sync` or for another client.
+   */
+  authenticate(authorization: string | undefined) {
+    const m = /^Bearer\s+(\S+)$/i.exec(authorization ?? "");
+    const entry = m ? this.validAccessToken(m[1]) : null;
+    if (!entry) throw new SyncProblem("invalid_token", "missing, invalid or expired access token");
+    if (!entry.scopes.includes("sync") || !this.opts.clientIDs.includes(entry.clientID))
+      throw new SyncProblem("invalid_token", "token lacks scope sync", 403);
+  }
+
+  // ── Devices ──
+
+  private assertNotRevoked(deviceID: string) {
+    if (this.devs.get(deviceID)?.revokedAt != null) throw new SyncProblem("device_revoked");
+  }
+
+  /** Register a device implicitly / bump `lastSeen`. */
+  touchDevice(deviceID: string) {
+    this.putDevice(deviceID, {});
+  }
+
+  putDevice(deviceID: string, input: DeviceInput): Device {
+    this.assertNotRevoked(deviceID);
+    const now = this.now();
+    const d = this.devs.get(deviceID) ?? {
+      id: deviceID,
+      name: null,
+      browser: null,
+      extVersion: null,
+      createdAt: now,
+      lastSeen: now,
+      revokedAt: null,
+    };
+    d.name = input.name ?? d.name;
+    d.browser = input.browser ?? d.browser;
+    d.extVersion = input.extVersion ?? d.extVersion;
+    d.lastSeen = now;
+    this.devs.set(deviceID, d);
+    const { revokedAt: _, ...device } = d;
+    return clone(device);
+  }
+
+  /** Live devices, most recently seen first. */
+  listDevices(): Device[] {
+    return [...this.devs.values()]
+      .filter((d) => d.revokedAt === null)
+      .sort((a, b) => b.lastSeen - a.lastSeen)
+      .map(({ revokedAt: _, ...d }) => clone(d));
+  }
+
+  /** Returns false for an unknown or already revoked device. */
+  revokeDevice(deviceID: string): boolean {
+    const d = this.devs.get(deviceID);
+    if (!d || d.revokedAt !== null) return false;
+    d.revokedAt = this.now();
+    return true;
+  }
+
+  // ── Records ──
+
+  /** `GET /changes`. Throws 410 `cursor_expired` when 0 < since < purged rev. */
+  changes(since = 0, limit: number = SYNC_LIMITS.changesDefaultLimit): ChangesResult {
+    const lim = Math.min(Math.max(limit, 1), SYNC_LIMITS.changesMaxLimit);
+    // since=0 is a full resync and always allowed (as on the real server)
+    if (since > 0 && since < this.purgedRev) throw new SyncProblem("cursor_expired");
+    const rows = [...this.recs.values()]
+      .filter((r) => r.rev > since)
+      .sort((a, b) => a.rev - b.rev);
+    const page = rows.slice(0, lim);
+    return {
+      records: page.map(clone),
+      cursor: page.length ? page[page.length - 1].rev : Math.max(since, this.rev),
+      hasMore: rows.length > lim,
+    };
+  }
+
+  private totals() {
+    let n = 0;
+    let bytes = 0;
+    for (const r of this.recs.values()) {
+      n++;
+      if (!r.deleted) bytes += utf8Length(JSON.stringify(r.data));
+    }
+    return { n, bytes };
+  }
+
+  /**
+   * `POST /records`: each record on its own, in order. Results keep request
+   * order per bucket; as on the real server, validation rejects come first.
+   */
+  push(records: unknown[], deviceID = "00000000-0000-4000-8000-000000000000"): PushResult {
+    if (!Array.isArray(records) || records.length < 1 || records.length > SYNC_LIMITS.recordsPerPush)
+      throw new SyncProblem(
+        "invalid_request",
+        `Body must be { records: [...] } with 1 to ${SYNC_LIMITS.recordsPerPush} records`
+      );
+    this.assertNotRevoked(deviceID);
+
+    const invalid: PushResult["rejected"] = [];
+    const valid: PushRecord[] = [];
+    for (const input of records) {
+      const v = validatePushRecord(input);
+      if (v.ok) valid.push(v.record);
+      else invalid.push({ id: v.id, reason: v.reason });
+    }
+
+    const result: PushResult = { accepted: [], rejected: invalid };
+    for (const rec of valid) {
+      if (hlcTime(rec.hlc) > this.now() + SYNC_LIMITS.clockSkewMs) {
+        result.rejected.push({ id: rec.id, reason: "clock_skew" });
+        continue;
+      }
+      const stored = this.recs.get(rec.id);
+      if (stored && rec.hlc === stored.hlc) {
+        result.accepted.push({ id: rec.id, rev: stored.rev });
+        continue;
+      }
+      if (stored && rec.hlc < stored.hlc) {
+        result.rejected.push({ id: rec.id, reason: "stale", current: clone(stored) });
+        continue;
+      }
+      const data = rec.deleted ? null : rec.data;
+      const size = rec.deleted ? 0 : utf8Length(JSON.stringify(data));
+      const totals = this.totals();
+      const n = totals.n + (stored ? 0 : 1);
+      const storedSize = stored && !stored.deleted ? utf8Length(JSON.stringify(stored.data)) : 0;
+      if (n > this.opts.maxRecords || totals.bytes - storedSize + size > this.opts.maxBytes) {
+        result.rejected.push({ id: rec.id, reason: "quota_exceeded" });
+        continue;
+      }
+      const row: SyncRecord = {
+        id: rec.id,
+        rev: ++this.rev,
+        hlc: rec.hlc,
+        deviceID,
+        deleted: rec.deleted,
+        schema: rec.schema,
+        encoding: rec.encoding,
+        data: clone(data),
+      };
+      this.recs.set(rec.id, row);
+      result.accepted.push({ id: rec.id, rev: row.rev });
+    }
+    return result;
+  }
+
+  // ── Snapshots ──
+
+  createSnapshot(createdBy: string, reason: SnapshotReason = "manual"): SnapshotMeta {
+    const records = this.records().filter((r) => !r.deleted);
+    const snap: Snapshot = {
+      id: randomUUID(),
+      createdAt: this.now(),
+      reason,
+      rev: this.rev,
+      recordCount: records.length,
+      createdBy,
+      records,
+      seq: ++this.snapSeq,
+    };
+    this.snaps.push(snap);
+    return this.metaOf(snap);
+  }
+
+  private metaOf({ id, createdAt, reason, rev, recordCount, createdBy }: Snapshot): SnapshotMeta {
+    return { id, createdAt, reason, rev, recordCount, createdBy };
+  }
+
+  /** Newest first. */
+  listSnapshots(): SnapshotMeta[] {
+    return [...this.snaps]
+      .sort((a, b) => b.createdAt - a.createdAt || b.rev - a.rev || b.seq - a.seq)
+      .map((s) => this.metaOf(s));
+  }
+
+  private findSnapshot(id: string): Snapshot {
+    const snap = this.snaps.find((s) => s.id === id);
+    if (!snap) throw new SyncProblem("not_found", "snapshot");
+    return snap;
+  }
+
+  getSnapshot(id: string): { records: SyncRecord[] } {
+    return { records: clone(this.findSnapshot(id).records) };
+  }
+
+  /**
+   * Restore (§6.3): a `before-restore` snapshot, then every snapshot record
+   * and a tombstone for every live record absent from it, as new writes with
+   * HLC `max(maxStoredT + 1, now):0000:server`. Quotas are not enforced.
+   */
+  restore(id: string, deviceID: string): { rev: number; written: number } {
+    this.assertNotRevoked(deviceID);
+    const snap = this.findSnapshot(id);
+    this.createSnapshot(deviceID, "before-restore");
+    let maxT = 0;
+    for (const r of this.recs.values()) maxT = Math.max(maxT, hlcTime(r.hlc));
+    const hlc = formatHlc(Math.max(maxT + 1, this.now()), 0, "server");
+
+    const keep = new Set(snap.records.map((r) => r.id));
+    const live = [...this.recs.values()].filter((r) => !r.deleted && !keep.has(r.id));
+    let written = 0;
+    for (const r of snap.records) {
+      this.recs.set(r.id, { ...clone(r), rev: ++this.rev, hlc, deviceID, deleted: false });
+      written++;
+    }
+    for (const r of live) {
+      this.recs.set(r.id, { ...r, rev: ++this.rev, hlc, deviceID, deleted: true, data: null });
+      written++;
+    }
+    return { rev: this.rev, written };
+  }
+
+  // ── HTTP dispatch (no sockets) ──
+
+  /** Discovery metadata (RFC 8414) for a server at `origin`. */
+  metadata(origin: string) {
+    const issuer = `${origin}/api/auth`;
+    return {
+      issuer,
+      authorization_endpoint: `${origin}${OAUTH_BASE_PATH}/authorize`,
+      token_endpoint: `${origin}${OAUTH_BASE_PATH}/token`,
+      revocation_endpoint: `${origin}${OAUTH_BASE_PATH}/revoke`,
+      userinfo_endpoint: `${origin}${OAUTH_BASE_PATH}/userinfo`,
+      scopes_supported: SUPPORTED_SCOPES,
+      response_types_supported: ["code"],
+      grant_types_supported: ["authorization_code", "refresh_token"],
+      code_challenge_methods_supported: ["S256"],
+      token_endpoint_auth_methods_supported: ["none"],
+    };
+  }
+
+  /** Answer one request. Never throws. */
+  handle(req: SyncRequest): SyncResponse {
+    const url = new URL(req.url);
+    const method = req.method.toUpperCase();
+    const entry: RequestLogEntry = {
+      method,
+      path: url.pathname,
+      query: Object.fromEntries(url.searchParams),
+      status: 0,
+      device: req.headers["x-proxyverse-device"],
+      version: req.headers["x-proxyverse-version"],
+      time: Date.now(),
+    };
+    if (req.body) {
+      try {
+        entry.body = (req.headers["content-type"] ?? "").includes("application/x-www-form-urlencoded")
+          ? Object.fromEntries(new URLSearchParams(req.body))
+          : JSON.parse(req.body);
+      } catch {
+        entry.body = req.body;
+      }
+    }
+
+    let res: SyncResponse;
+    try {
+      res = this.route(method, url, req);
+    } catch (err) {
+      if (err instanceof SyncProblem) res = problemResponse(err);
+      else if (err instanceof OAuthError) res = jsonResponse(err.body, err.status);
+      else
+        res = problemResponse(
+          new SyncProblem("unavailable", err instanceof Error ? err.message : String(err), 503)
+        );
+    }
+    entry.status = res.status;
+    if (res.status >= 400) {
+      try {
+        const body = JSON.parse(res.body);
+        entry.code = body.code ?? body.error;
+      } catch {
+        /* not JSON */
+      }
+    }
+    this.log.push(entry);
+    return res;
+  }
+
+  /**
+   * A `fetch` drop-in over `handle()`, for unit tests: absolute URLs only;
+   * the origin is ignored except for discovery metadata.
+   */
+  fetch = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const request = new Request(input, init);
+    const headers: Record<string, string> = {};
+    request.headers.forEach((v, k) => (headers[k] = v));
+    const body = request.body ? await request.text() : undefined;
+    const res = this.handle({ method: request.method, url: request.url, headers, body });
+    const nullBody = res.status === 204 || res.status === 304 || (res.status >= 300 && res.status < 400 && !res.body);
+    return new Response(nullBody ? null : res.body, { status: res.status, headers: res.headers });
+  };
+
+  private takeFailure(method: string, path: string): Failure | undefined {
+    const i = this.failures.findIndex(
+      (f) => (!f.path || path.includes(f.path)) && (!f.method || f.method.toUpperCase() === method)
+    );
+    return i < 0 ? undefined : this.failures.splice(i, 1)[0];
+  }
+
+  private route(method: string, url: URL, req: SyncRequest): SyncResponse {
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+
+    const failure = this.takeFailure(method, path);
+    if (failure)
+      throw new SyncProblem(failure.code, failure.detail, failure.status, failure.retryAfter);
+
+    if (path === "/.well-known/oauth-authorization-server" && method === "GET")
+      return jsonResponse(this.metadata(url.origin));
+
+    if (path.startsWith(OAUTH_BASE_PATH + "/")) return this.routeOAuth(method, path.slice(OAUTH_BASE_PATH.length), url, req);
+
+    if (path.startsWith(SYNC_BASE_PATH + "/")) return this.routeSync(method, path.slice(SYNC_BASE_PATH.length), url, req);
+
+    throw new SyncProblem("not_found", `no route for ${method} ${path}`);
+  }
+
+  private routeOAuth(method: string, sub: string, url: URL, req: SyncRequest): SyncResponse {
+    // Clients must not send byte.vet's cookies. byte.vet's auth server
+    // refuses cookie-bearing cross-site POSTs (its token endpoint did until
+    // it learned to ignore them); enforcing it here keeps the client honest.
+    if (method === "POST" && req.headers.cookie) {
+      return jsonResponse({ message: "Missing or null Origin", code: "MISSING_OR_NULL_ORIGIN" }, 403);
+    }
+    const form = () => Object.fromEntries(new URLSearchParams(req.body ?? "")) as Record<string, string>;
+    if (sub === "/authorize" && method === "GET") {
+      const q = url.searchParams;
+      const location = this.authorize({
+        client_id: q.get("client_id"),
+        redirect_uri: q.get("redirect_uri"),
+        code_challenge: q.get("code_challenge"),
+        code_challenge_method: q.get("code_challenge_method"),
+        state: q.get("state"),
+        scope: q.get("scope"),
+        response_type: q.get("response_type"),
+      });
+      // signing in leaves a session cookie, as on byte.vet
+      return {
+        status: 302,
+        headers: {
+          location,
+          "cache-control": "no-store",
+          "set-cookie": "e2e.session_token=signed-in; Path=/; HttpOnly; SameSite=Lax",
+        },
+        body: "",
+      };
+    }
+    if (sub === "/token" && method === "POST") return jsonResponse(this.token(form()));
+    if (sub === "/revoke" && method === "POST") {
+      this.revoke(form().token ?? "");
+      return { status: 200, headers: { "cache-control": "no-store" }, body: "" };
+    }
+    if (sub === "/userinfo" && (method === "GET" || method === "POST")) {
+      const m = /^Bearer\s+(\S+)$/i.exec(req.headers.authorization ?? "");
+      return jsonResponse(this.userinfo(m?.[1] ?? ""));
+    }
+    throw new OAuthError("invalid_request", `no route for ${method} ${sub}`, 404);
+  }
+
+  private routeSync(method: string, sub: string, url: URL, req: SyncRequest): SyncResponse {
+    // same order as the real server: bearer, device header, version, liveness
+    this.authenticate(req.headers.authorization);
+    const deviceID = req.headers["x-proxyverse-device"];
+    if (!isUUID(deviceID)) throw new SyncProblem("invalid_request", "X-Proxyverse-Device must be a UUID");
+    const version = req.headers["x-proxyverse-version"];
+    if (!version) throw new SyncProblem("invalid_request", "X-Proxyverse-Version is required");
+    if (this.opts.minVersion && compareVersions(version, this.opts.minVersion) < 0)
+      throw new SyncProblem("client_too_old", `Proxyverse ${this.opts.minVersion} or newer is required to sync`);
+
+    if (req.body && utf8Length(req.body) > SYNC_LIMITS.requestBodyBytes)
+      throw new SyncProblem("invalid_request", "Request body exceeds 2 MiB");
+    const json = (): unknown => {
+      if (!req.body) return null;
+      try {
+        return JSON.parse(req.body);
+      } catch {
+        throw new SyncProblem("invalid_request", "Body is not valid JSON");
+      }
+    };
+
+    const deviceMatch = /^\/devices\/([^/]+)$/.exec(sub);
+    // PUT /devices/{id} registers the device itself
+    if (!(deviceMatch && method === "PUT")) this.touchDevice(deviceID);
+
+    if (sub === "/devices" && method === "GET") return jsonResponse(this.listDevices());
+
+    if (deviceMatch) {
+      const id = decodeURIComponent(deviceMatch[1]);
+      if (!isUUID(id)) throw new SyncProblem("invalid_request", "deviceID must be a UUID");
+      if (method === "PUT") {
+        const body = json();
+        if (!isPlainObject(body)) throw new SyncProblem("invalid_request", "Body must be an object");
+        const field = (k: keyof DeviceInput) => {
+          const v = body[k];
+          if (v === undefined || v === null) return undefined;
+          if (typeof v !== "string" || v.length > 200)
+            throw new SyncProblem("invalid_request", `${k} must be a string of at most 200 characters`);
+          return v;
+        };
+        return jsonResponse(
+          this.putDevice(id, { name: field("name"), browser: field("browser"), extVersion: field("extVersion") })
+        );
+      }
+      if (method === "DELETE") {
+        if (!this.revokeDevice(id)) throw new SyncProblem("not_found", "Unknown device");
+        return { status: 204, headers: {}, body: "" };
+      }
+    }
+
+    if (sub === "/changes" && method === "GET") {
+      const int = (name: string, fallback: number) => {
+        const v = url.searchParams.get(name);
+        if (v === null || v === "") return fallback;
+        if (!/^\d+$/.test(v)) throw new SyncProblem("invalid_request", `${name} must be a non-negative integer`);
+        return Number(v);
+      };
+      return jsonResponse(this.changes(int("since", 0), int("limit", SYNC_LIMITS.changesDefaultLimit)));
+    }
+
+    if (sub === "/records" && method === "POST") {
+      const body = json();
+      if (!isPlainObject(body) || !Array.isArray(body.records))
+        throw new SyncProblem("invalid_request", "Body must be { records: [...] } with 1 to 100 records");
+      return jsonResponse(this.push(body.records, deviceID));
+    }
+
+    if (sub === "/snapshots" && method === "GET") return jsonResponse(this.listSnapshots());
+    if (sub === "/snapshots" && method === "POST") {
+      const body = json();
+      const reason = isPlainObject(body) && body.reason === "before-overwrite" ? "before-overwrite" : "manual";
+      return jsonResponse(this.createSnapshot(deviceID, reason), 201);
+    }
+
+    const snap = /^\/snapshots\/([^/]+)(\/restore)?$/.exec(sub);
+    if (snap) {
+      const id = decodeURIComponent(snap[1]);
+      if (!snap[2] && method === "GET") return jsonResponse(this.getSnapshot(id));
+      if (snap[2] && method === "POST") return jsonResponse(this.restore(id, deviceID));
+    }
+
+    throw new SyncProblem("not_found", `no route for ${method} ${sub}`);
+  }
+}
+
+function jsonResponse(body: unknown, status = 200): SyncResponse {
+  return {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+    body: JSON.stringify(body),
+  };
+}
+
+function problemResponse(p: SyncProblem): SyncResponse {
+  const headers: Record<string, string> = {
+    "content-type": "application/problem+json",
+    "cache-control": "no-store",
+  };
+  if (p.status === 401 && p.code === "invalid_token") headers["www-authenticate"] = 'Bearer error="invalid_token"';
+  if (p.retryAfter !== undefined || p.status === 429 || p.status === 503)
+    headers["retry-after"] = String(Math.max(0, Math.ceil(p.retryAfter ?? (p.status === 429 ? 60 : 30))));
+  return { status: p.status, headers, body: JSON.stringify(p.body) };
+}
diff --git a/e2e/specs/popup.e2e.ts b/e2e/specs/popup.e2e.ts
index 3399c24..d64d189 100644
--- a/e2e/specs/popup.e2e.ts
+++ b/e2e/specs/popup.e2e.ts
@@ -83,9 +83,9 @@ test.describe("popup", () => {
     await sw.setProfiles([proxyA]);
     const popup = await openPopup();
 
-    const home = await popup.openNewTab("popup-config");
-    await expect(home).toHaveURL(/#\/profiles\/new$/); // home redirects there
-    await home.close();
+    const preference = await popup.openNewTab("popup-config");
+    await expect(preference).toHaveURL(/#\/preference$/);
+    await preference.close();
 
     await popup.select("proxyA");
     const editor = await popup.openNewTab("popup-config");
diff --git a/e2e/specs/preference.e2e.ts b/e2e/specs/preference.e2e.ts
index 33c16f2..c594d67 100644
--- a/e2e/specs/preference.e2e.ts
+++ b/e2e/specs/preference.e2e.ts
@@ -1,6 +1,6 @@
 import { test, expect } from "../fixtures";
 import { expectRoute } from "../fixtures/routing";
-import { chooseOption, toast } from "../pages/arco";
+import { chooseOption, popconfirmOK, toast } from "../pages/arco";
 import { Preference } from "../pages/preference";
 import {
   autoProfile,
@@ -92,9 +92,7 @@ test.describe("preference", () => {
     await expect(page.getByText("界面", { exact: true })).toBeVisible();
     // Arco's own texts follow
     await importButton.click();
-    await expect(
-      page.locator(".arco-popconfirm:visible .arco-btn-primary")
-    ).toHaveText("确定");
+    await expect(popconfirmOK(page)).toHaveText("确定");
     // so do the other open pages
     await expect(popup.page.getByTestId("popup-profile-direct")).toHaveText(
       "直接连接"
diff --git a/e2e/specs/sync.e2e.ts b/e2e/specs/sync.e2e.ts
new file mode 100644
index 0000000..cc83cb6
--- /dev/null
+++ b/e2e/specs/sync.e2e.ts
@@ -0,0 +1,195 @@
+import type { SyncSettings } from "@/services/sync/state";
+import { test, expect } from "../fixtures";
+import { expectRoute } from "../fixtures/routing";
+import { proxyProfile, server, standardProfiles } from "../data/profiles";
+import {
+  CLIENT_ID,
+  expectSynced,
+  remoteProfile,
+  signInDirectly,
+  SyncSection,
+  useFakeByteVet,
+} from "../pages/sync";
+
+// Cloud sync against the fake byte.vet (e2e/servers/syncApi.ts). It runs on
+// loopback, so sync traffic never goes through the profile under test.
+
+test.describe("sync", () => {
+  test("signs in through the browser's auth window and uploads the profiles", async ({
+    sw,
+    servers,
+    openConfig,
+  }) => {
+    const { proxyA } = standardProfiles(servers);
+    await sw.setProfiles([proxyA]);
+    await useFakeByteVet(sw, servers);
+
+    const page = await openConfig("/preference");
+    const sync = new SyncSection(page);
+    await sync.byId("pref-sync-signin").click();
+
+    await expect(sync.byId("pref-sync-account")).toHaveText(
+      servers.sync.user.email
+    );
+    await expect
+      .poll(() => servers.sync.get("profile:proxyA")?.data)
+      .toMatchObject({ profileID: "proxyA", profileName: "Proxy A" });
+    await expect(sync.byId("pref-sync-status")).toContainText(/Last synced/);
+
+    // the PKCE exchange really happened, as the dev client
+    const token = servers.sync.requests("/oauth2/token", "POST")[0];
+    expect(token.body).toMatchObject({
+      grant_type: "authorization_code",
+      client_id: CLIENT_ID,
+    });
+  });
+
+  test("pushes a local edit a moment after it's saved", async ({
+    sw,
+    servers,
+  }) => {
+    const { proxyA } = standardProfiles(servers);
+    await sw.setProfiles([proxyA]);
+    await signInDirectly(sw, servers);
+    await expect.poll(() => servers.sync.get("profile:proxyA")).toBeDefined();
+
+    await sw.setProfiles([{ ...proxyA, profileName: "Renamed" }]);
+    await expect
+      .poll(() => servers.sync.get("profile:proxyA")?.data)
+      .toMatchObject({ profileName: "Renamed" });
+  });
+
+  test("applies remote changes on Sync now and on the poll alarm", async ({
+    sw,
+    servers,
+    openConfig,
+  }) => {
+    const { proxyA, proxyB } = standardProfiles(servers);
+    await signInDirectly(sw, servers);
+    await expectSynced(sw);
+    expect((await sw.getAlarms()).map((a) => a.name)).toContain("sync:poll");
+
+    const page = await openConfig("/preference");
+    servers.sync.seed([remoteProfile(proxyA)]);
+    await new SyncSection(page).syncNow();
+    await expect.poll(async () => Object.keys(await sw.getProfiles())).toEqual(["proxyA"]);
+
+    servers.sync.seed([remoteProfile(proxyB)]);
+    await sw.fireAlarm("sync:poll");
+    await expect
+      .poll(async () => Object.keys(await sw.getProfiles()).sort())
+      .toEqual(["proxyA", "proxyB"]);
+  });
+
+  test("a remote deletion of the active profile switches to direct", async ({
+    sw,
+    servers,
+    page,
+    openConfig,
+    activate,
+  }) => {
+    const { proxyA } = standardProfiles(servers);
+    await sw.setProfiles([proxyA]);
+    await signInDirectly(sw, servers);
+    await expect.poll(() => servers.sync.get("profile:proxyA")).toBeDefined();
+
+    await activate("proxyA");
+    const site = servers.url("sync-delete.test");
+    await expectRoute(page, site, "proxyA");
+
+    servers.sync.seed([remoteProfile(proxyA, true)]);
+    await new SyncSection(await openConfig("/preference")).syncNow();
+    await expect.poll(() => sw.getProfiles()).toEqual({});
+    await expectRoute(page, site, "direct");
+  });
+
+  test("a local-only profile stays on this device", async ({
+    sw,
+    servers,
+    openEditor,
+  }) => {
+    const { proxyA, proxyB } = standardProfiles(servers);
+    await useFakeByteVet(sw, servers);
+    await sw.eval(
+      () => chrome.storage.local.set({ "sync.settings": { syncPrefs: true, localOnly: ["proxyA"] } })
+    );
+    await sw.setProfiles([proxyA, proxyB]);
+    await signInDirectly(sw, servers);
+    await expect.poll(() => servers.sync.get("profile:proxyB")).toBeDefined();
+    expect(servers.sync.get("profile:proxyA")).toBeUndefined();
+
+    // marking a synced profile local-only in the editor detaches it
+    const editor = await openEditor("proxyB");
+    await editor.byId("profile-local-only").click();
+    await editor.saveOK();
+    await expect
+      .poll(async () => ((await sw.getLocal("sync.settings")) as SyncSettings | undefined)?.localOnly)
+      .toEqual(["proxyA", "proxyB"]);
+
+    await sw.setProfiles([proxyA, { ...proxyB, profileName: "Private now" }]);
+    // nothing to push, so the run after the change records nothing: sync
+    // explicitly to be sure the edit had its chance to leave
+    const since = Date.now();
+    await editor.page.goto(`${sw.origin}/index.html#/preference`);
+    await new SyncSection(editor.page).syncNow();
+    await expectSynced(sw, since);
+    expect(servers.sync.get("profile:proxyB")?.data).toMatchObject({
+      profileName: "Proxy B",
+    });
+  });
+
+  test("a change made just before the service worker stops still syncs", async ({
+    sw,
+    servers,
+  }) => {
+    await signInDirectly(sw, servers);
+    await expectSynced(sw);
+
+    const p = proxyProfile({ profileID: "late" }, { default: server(servers.ports.proxyA) });
+    await sw.setProfiles([p]);
+    await sw.restart(); // before the 2 s debounce fires
+    await expect.poll(() => servers.sync.get("profile:late")).toBeDefined();
+  });
+
+  test("asks how to combine data on the first sign-in, then merges", async ({
+    sw,
+    servers,
+    openConfig,
+  }) => {
+    const { proxyA, proxyB } = standardProfiles(servers);
+    servers.sync.seed([remoteProfile(proxyB)]);
+    await sw.setProfiles([proxyA]);
+    await signInDirectly(sw, servers);
+
+    const page = await openConfig("/preference");
+    const sync = new SyncSection(page);
+    await expect(sync.byId("pref-sync-first-choice")).toBeVisible();
+    expect(servers.sync.get("profile:proxyA")).toBeUndefined();
+
+    await sync.byId("pref-sync-choice-merge").click();
+    await expect(sync.byId("pref-sync-first-choice")).toBeHidden();
+    await expect
+      .poll(async () => Object.keys(await sw.getProfiles()).sort())
+      .toEqual(["proxyA", "proxyB"]);
+    expect(servers.sync.get("profile:proxyA")).toBeDefined();
+  });
+
+  test("restores a snapshot", async ({ sw, servers, openConfig }) => {
+    const { proxyA } = standardProfiles(servers);
+    await sw.setProfiles([proxyA]);
+    await signInDirectly(sw, servers);
+    await expect.poll(() => servers.sync.get("profile:proxyA")).toBeDefined();
+    const snapshot = servers.sync.createSnapshot("e2e");
+
+    await sw.setProfiles([]);
+    await expect
+      .poll(() => servers.sync.get("profile:proxyA")?.deleted)
+      .toBe(true);
+
+    const page = await openConfig("/preference");
+    const sync = new SyncSection(page);
+    await sync.byId("pref-sync-snapshots").click();
+    await sync.confirm(`pref-sync-restore-${snapshot.id}`);
+    await expect.poll(async () => Object.keys(await sw.getProfiles())).toEqual(["proxyA"]);
+  });
+});
diff --git a/manifest.json b/manifest.json
index dfebb43..9bf707a 100644
--- a/manifest.json
+++ b/manifest.json
@@ -28,6 +28,7 @@
     "webRequestAuthProvider",
     "activeTab",
     "alarms",
-    "sidePanel"
+    "sidePanel",
+    "identity"
   ]
 }
diff --git a/package.json b/package.json
index 381ce97..f7ec066 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,11 @@
     "test:e2e": "playwright test -c e2e",
     "test:e2e:chromium": "E2E_TARGET=chrome playwright test -c e2e --project chromium",
     "test:e2e:firefox": "E2E_TARGET=firefox playwright test -c e2e --project firefox-smoke",
-    "test:e2e:typecheck": "tsc -p e2e"
+    "test:e2e:typecheck": "tsc -p e2e",
+    "test:e2e:live": "playwright test -c e2e/live",
+    "sync:api-types": "node scripts/sync-api-types.mjs",
+    "build:preview": "PROXYVERSE_ENV=northernlight npm run build",
+    "build:preview:firefox": "PROXYVERSE_ENV=northernlight npm run build:firefox -- --outDir dist-firefox --emptyOutDir"
   },
   "directories": {
     "test": "tests"
diff --git a/public/_locales/ar/messages.json b/public/_locales/ar/messages.json
index 8e61c9f..b3b5add 100644
--- a/public/_locales/ar/messages.json
+++ b/public/_locales/ar/messages.json
@@ -361,14 +361,6 @@
     "message": "الاستيراد والتصدير"
   },
 
-  "preferences_section_import_export_desc": {
-    "message": "صدّر ملفات تعريف الوكيل إلى ملف للنسخ الاحتياطي أو المشاركة، أو استوردها لاستعادتها عند الحاجة."
-  },
-
-  "preferences_section_import_switchyomega": {
-    "message": "يقبل خيار «استيراد ملفات التعريف» أيضًا نسخة احتياطية من ProxySwitchyOmega أو ZeroOmega بامتداد (.bak). تظهر بعد الاستيراد قائمة بكل ما تعذّر تحويله بدقة."
-  },
-
   "preferences_tag_beta": {
     "message": "تجريبي"
   },
diff --git a/public/_locales/en/messages.json b/public/_locales/en/messages.json
index 690abde..d27b615 100644
--- a/public/_locales/en/messages.json
+++ b/public/_locales/en/messages.json
@@ -360,14 +360,23 @@
   "preferences_section_import_export": {
     "message": "Import & Export"
   },
-
-  "preferences_section_import_export_desc": {
-    "message": "Export your proxy profiles to a file for backup or sharing, or import them to restore profiles when needed."
+  "preferences_export": {
+    "message": "Export"
   },
-
-  "preferences_section_import_switchyomega": {
-    "message": "Import Profiles also accepts a ProxySwitchyOmega / ZeroOmega backup (.bak). Anything that can't be converted exactly is listed after the import."
+  "preferences_export_hint": {
+    "message": "Save your proxy profiles to a file, for backup or sharing."
+  },
+  "preferences_import": {
+    "message": "Import"
+  },
+  "preferences_import_hint": {
+    "message": "Restore profiles from a Proxyverse file."
   },
+  "preferences_import_switchyomega_hint": {
+    "message": "Also reads ProxySwitchyOmega / ZeroOmega backups (.bak). Anything that can't be converted exactly is listed after the import."
+  },
+
+
 
   "preferences_tag_beta": {
     "message": "Beta"
@@ -468,6 +477,157 @@
     "message": "<div class=\"arco-typography\"> Due to Firefox's restrictions, Proxyverse does not work properly as it's not enabled in private browsing windows. </div>\n<div class=\"arco-typography\"> Please enable the extension in private windows. </div>\n<div class=\"arco-typography\"><a class=\"arco-link arco-link-status-normal\" href=\"https://mzl.la/3pbGH96\">Learn more</a></div>"
   },
 
+  "preferences_section_sync": {
+    "message": "Sync"
+  },
+  "sync_desc": {
+    "message": "Sync your profiles and preferences across browsers and devices with a byte.vet account."
+  },
+  "sync_privacy_note": {
+    "message": "Profiles sync with everything in them, including proxy usernames and passwords. They're sent over an encrypted connection, stored encrypted, and used only to keep your devices in sync. Mark a profile \"This device only\" to keep it off the cloud."
+  },
+  "sync_action_signin": {
+    "message": "Sign in to sync"
+  },
+  "sync_signin_expired": {
+    "message": "The sign-in of $1 expired. Sign in again to keep syncing."
+  },
+  "sync_account": {
+    "message": "Account"
+  },
+  "sync_account_unknown": {
+    "message": "Signed in"
+  },
+  "sync_action_signout": {
+    "message": "Sign out"
+  },
+  "sync_signout_confirm": {
+    "message": "Stop syncing on this browser? Your profiles stay here."
+  },
+  "sync_status": {
+    "message": "Status"
+  },
+  "sync_action_now": {
+    "message": "Sync now"
+  },
+  "sync_time_recent": {
+    "message": "a few seconds ago"
+  },
+  "sync_status_never": {
+    "message": "Not synced yet."
+  },
+  "sync_status_ok": {
+    "message": "Last synced $1."
+  },
+  "sync_status_failed": {
+    "message": "$1 item(s) couldn't be synced: the server refused them. Edit them to try again."
+  },
+  "sync_status_held": {
+    "message": "$1 item(s) were synced by a newer Proxyverse and can't be read by this version. Update Proxyverse to use them."
+  },
+  "sync_error_auth": {
+    "message": "Sync stopped $1: sign in again."
+  },
+  "sync_error_clock_skew": {
+    "message": "Synced $1, but some changes were refused because this device's clock is ahead. Check the system clock."
+  },
+  "sync_error_unreachable": {
+    "message": "Sync failed $1: byte.vet can't be reached. Proxyverse will retry."
+  },
+  "sync_error_client_too_old": {
+    "message": "Sync stopped $1: this version of Proxyverse is too old. Update it to keep syncing."
+  },
+  "sync_error_quota": {
+    "message": "Sync failed $1: the account is full. Delete some profiles."
+  },
+  "sync_error_other": {
+    "message": "Sync failed $1 ($2)."
+  },
+  "sync_prefs": {
+    "message": "Sync preferences"
+  },
+  "sync_prefs_hint": {
+    "message": "Theme, language and toolbar button behavior. Turn off to keep this browser's own."
+  },
+  "sync_snapshots": {
+    "message": "Snapshots"
+  },
+  "sync_snapshots_hint": {
+    "message": "byte.vet keeps copies of your synced data, so a bad change can be undone."
+  },
+  "sync_action_snapshots": {
+    "message": "Restore…"
+  },
+  "sync_snapshots_desc": {
+    "message": "Restoring a snapshot replaces the synced data on every device. A snapshot of the current data is taken first."
+  },
+  "sync_snapshot_meta": {
+    "message": "$1, $2 item(s)"
+  },
+  "sync_snapshot_reason_daily": {
+    "message": "Daily"
+  },
+  "sync_snapshot_reason_manual": {
+    "message": "Manual"
+  },
+  "sync_snapshot_reason_before_restore": {
+    "message": "Before a restore"
+  },
+  "sync_snapshot_reason_before_overwrite": {
+    "message": "Before an upload"
+  },
+  "sync_action_restore": {
+    "message": "Restore"
+  },
+  "sync_restore_confirm": {
+    "message": "Replace the synced data on every device with this snapshot?"
+  },
+  "sync_restore_done": {
+    "message": "Restored. Other devices get it when they next sync."
+  },
+  "sync_first_title": {
+    "message": "Your account already has data"
+  },
+  "sync_first_desc": {
+    "message": "Both this browser and your byte.vet account have profiles. How should they be combined?"
+  },
+  "sync_first_merge": {
+    "message": "Merge both"
+  },
+  "sync_first_merge_hint": {
+    "message": "Keep everything. Where both have the same profile, this browser's wins."
+  },
+  "sync_first_cloud": {
+    "message": "Use the account's data"
+  },
+  "sync_first_cloud_hint": {
+    "message": "Replace this browser's profiles with the account's."
+  },
+  "sync_first_cloud_confirm": {
+    "message": "Profiles that are only in this browser will be deleted. Continue?"
+  },
+  "sync_first_backup": {
+    "message": "Download a backup first"
+  },
+  "sync_first_upload": {
+    "message": "Upload this browser's data"
+  },
+  "sync_first_upload_hint": {
+    "message": "Replace the account's profiles with this browser's, on every device. A snapshot is taken first."
+  },
+  "sync_first_upload_confirm": {
+    "message": "Profiles that are only in the account will be deleted on every device. Continue?"
+  },
+  "profile_local_only": {
+    "message": "This device only"
+  },
+  "profile_local_only_hint": {
+    "message": "Never sync this profile. Other devices keep the copy they already have."
+  },
+  "profile_local_only_referenced": {
+    "message": "Synced profiles route to this one: $1. On other devices those rules will point to a missing profile."
+  },
+
   "_": {
     "message": "<DUMMY>"
   }
diff --git a/public/_locales/pt_BR/messages.json b/public/_locales/pt_BR/messages.json
index 9a763a3..9c64862 100644
--- a/public/_locales/pt_BR/messages.json
+++ b/public/_locales/pt_BR/messages.json
@@ -361,14 +361,6 @@
     "message": "Importação e exportação"
   },
 
-  "preferences_section_import_export_desc": {
-    "message": "Exporte seus perfis de proxy para um arquivo para backup ou compartilhamento, ou importe-os para restaurar perfis quando necessário."
-  },
-
-  "preferences_section_import_switchyomega": {
-    "message": "\"Importar perfis\" também aceita um backup do ProxySwitchyOmega / ZeroOmega (.bak). O que não puder ser convertido exatamente será listado após a importação."
-  },
-
   "preferences_tag_beta": {
     "message": "Beta"
   },
diff --git a/public/_locales/zh_CN/messages.json b/public/_locales/zh_CN/messages.json
index c5e9de1..22accd2 100644
--- a/public/_locales/zh_CN/messages.json
+++ b/public/_locales/zh_CN/messages.json
@@ -361,14 +361,6 @@
     "message": "导入 / 导出"
   },
 
-  "preferences_section_import_export_desc": {
-    "message": "将代理配置导出成文件以便进行备份或分享，也可导入文件还原配置。"
-  },
-
-  "preferences_section_import_switchyomega": {
-    "message": "“导入配置”也支持 ProxySwitchyOmega / ZeroOmega 的备份文件（.bak）。无法完全转换的内容会在导入后列出。"
-  },
-
   "preferences_tag_beta": {
     "message": "Beta"
   },
diff --git a/public/_locales/zh_TW/messages.json b/public/_locales/zh_TW/messages.json
index 0d3b8b2..65b74fe 100644
--- a/public/_locales/zh_TW/messages.json
+++ b/public/_locales/zh_TW/messages.json
@@ -361,14 +361,6 @@
     "message": "匯入與匯出設定檔"
   },
 
-  "preferences_section_import_export_desc": {
-    "message": "將您的代理伺服器設定檔匯出至檔案，以便備份或分享，並可匯入以還原。"
-  },
-
-  "preferences_section_import_switchyomega": {
-    "message": "「匯入設定檔」也支援 ProxySwitchyOmega / ZeroOmega 的備份檔（.bak）。無法完整轉換的項目會在匯入後列出。"
-  },
-
   "preferences_tag_beta": {
     "message": "Beta"
   },
diff --git a/scripts/sync-api-types.mjs b/scripts/sync-api-types.mjs
new file mode 100644
index 0000000..2501509
--- /dev/null
+++ b/scripts/sync-api-types.mjs
@@ -0,0 +1,32 @@
+// Regenerates src/services/sync/api.gen.ts from the vendored sync API
+// contract (docs/sync-api.openapi.yaml), and stamps it with the contract's
+// SHA-256 so a unit test notices when the two drift apart.
+//
+// openapi-typescript runs through npx rather than as a dependency: its
+// TypeScript peer is 5.x and this repo is on 6.x.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const SPEC = "docs/sync-api.openapi.yaml";
+const OUT = "src/services/sync/api.gen.ts";
+
+execFileSync(
+  "npx",
+  ["-y", "openapi-typescript@7.13.0", SPEC, "-o", OUT],
+  { cwd: root, stdio: "inherit" }
+);
+
+const hash = createHash("sha256")
+  .update(readFileSync(`${root}/${SPEC}`))
+  .digest("hex");
+const generated = readFileSync(`${root}/${OUT}`, "utf8");
+writeFileSync(
+  `${root}/${OUT}`,
+  `// Generated from ${SPEC} by \`npm run sync:api-types\`.\n` +
+    `// openapi-sha256: ${hash}\n` +
+    generated
+);
diff --git a/src/adapters/base.ts b/src/adapters/base.ts
index e33e490..b9caaea 100644
--- a/src/adapters/base.ts
+++ b/src/adapters/base.ts
@@ -91,6 +91,27 @@ export function setMessageOverride(override: MessageOverride | undefined) {
   messageOverride = override;
 }
 
+/** The part of the browsers' `identity` API sign-in uses. */
+type IdentityAPI = {
+  launchWebAuthFlow(details: {
+    url: string;
+    interactive: boolean;
+  }): Promise<string | undefined>;
+  getRedirectURL(path: string): string;
+};
+
+export const IDENTITY_UNAVAILABLE =
+  "The identity API is unavailable in this browser";
+
+/** What this extension build runs on; sync names devices after it. */
+export type ExtensionInfo = {
+  /** The manifest version, e.g. "2.3.0". */
+  version: string;
+  browser: "chrome" | "edge" | "firefox" | "web";
+  /** runtime.getPlatformInfo's os, e.g. "mac", "win", "linux". */
+  os: string;
+};
+
 export type ActionBehavior = "popup" | "sidebar";
 
 // the pages the toolbar icon opens
@@ -119,6 +140,7 @@ export abstract class BaseAdapter {
   // local storage
   abstract set<T>(key: string, val: T): Promise<void>;
   abstract get<T>(key: string): Promise<T | undefined>;
+  abstract remove(key: string): Promise<void>;
   async getWithDefault<T>(key: string, defaultVal: T): Promise<T> {
     const ret = await this.get<T>(key);
     if (ret === undefined) {
@@ -192,6 +214,30 @@ export abstract class BaseAdapter {
   handleToolbarClicks(): void {}
   abstract reloadTab(tabID: number): Promise<void>;
 
+  // identity: sign-in through a browser-hosted web auth flow (cloud sync).
+  // Chrome and Firefox share the API; it's absent where a browser lacks it
+  // (e.g. Firefox for Android, some Chromium forks).
+  protected identity(): IdentityAPI | undefined {
+    return undefined;
+  }
+
+  /** Resolves with the final redirect URL of the flow. */
+  async launchWebAuthFlow(url: string, interactive: boolean): Promise<string> {
+    const identity = this.identity();
+    if (!identity) throw new Error(IDENTITY_UNAVAILABLE);
+    const redirect = await identity.launchWebAuthFlow({ url, interactive });
+    if (!redirect) throw new Error("The web auth flow returned no redirect URL");
+    return redirect;
+  }
+
+  /** The extension's redirect URL for `path`, e.g. "/oauth". */
+  getRedirectURL(path: string): string {
+    const identity = this.identity();
+    if (!identity) throw new Error(IDENTITY_UNAVAILABLE);
+    return identity.getRedirectURL(path);
+  }
+  abstract extensionInfo(): Promise<ExtensionInfo>;
+
   // messages
   abstract onMessage(
     callback: (
diff --git a/src/adapters/chrome.ts b/src/adapters/chrome.ts
index b0b3601..de281ac 100644
--- a/src/adapters/chrome.ts
+++ b/src/adapters/chrome.ts
@@ -15,6 +15,7 @@ import {
   WebRequestErrorOccurredDetails,
   WebRequestResponseStartedDetails,
   ActionBehavior,
+  ExtensionInfo,
   POPUP_PAGE,
   SIDEBAR_PAGE,
 } from "./base";
@@ -35,6 +36,10 @@ export class Chrome extends BaseAdapter {
     return ret[key] as T | undefined;
   }
 
+  async remove(key: string): Promise<void> {
+    await chrome.storage.local.remove(key);
+  }
+
   onLocalStorageChanged(
     callback: (changes: Record<string, { newValue?: unknown; oldValue?: unknown }>) => void
   ): () => void {
@@ -153,6 +158,21 @@ export class Chrome extends BaseAdapter {
     await chrome.tabs.reload(tabID);
   }
 
+  protected identity() {
+    // typed as always there, but absent where the browser lacks the API
+    return chrome.identity as typeof chrome.identity | undefined;
+  }
+
+  async extensionInfo(): Promise<ExtensionInfo> {
+    const { os } = await chrome.runtime.getPlatformInfo();
+    return {
+      version: chrome.runtime.getManifest().version,
+      // Edge runs this adapter too; only its user agent tells them apart
+      browser: navigator.userAgent.includes("Edg/") ? "edge" : "chrome",
+      os,
+    };
+  }
+
   onMessage(
     callback: (
       message: any,
diff --git a/src/adapters/firefox.ts b/src/adapters/firefox.ts
index 59f95e7..d9b117c 100644
--- a/src/adapters/firefox.ts
+++ b/src/adapters/firefox.ts
@@ -13,6 +13,7 @@ import {
   WebRequestErrorOccurredDetails,
   WebRequestResponseStartedDetails,
   ActionBehavior,
+  ExtensionInfo,
   POPUP_PAGE,
 } from "./base";
 
@@ -31,6 +32,10 @@ export class Firefox extends BaseAdapter {
     return ret[key] as T | undefined;
   }
 
+  async remove(key: string): Promise<void> {
+    await browser.storage.local.remove(key);
+  }
+
   onLocalStorageChanged(
     callback: (changes: Record<string, { newValue?: unknown; oldValue?: unknown }>) => void
   ): () => void {
@@ -181,6 +186,20 @@ export class Firefox extends BaseAdapter {
     await browser.tabs.reload(tabID);
   }
 
+  protected identity() {
+    // typed as always there, but absent where the browser lacks the API
+    return browser.identity as typeof browser.identity | undefined;
+  }
+
+  async extensionInfo(): Promise<ExtensionInfo> {
+    const { os } = await browser.runtime.getPlatformInfo();
+    return {
+      version: browser.runtime.getManifest().version,
+      browser: "firefox",
+      os,
+    };
+  }
+
   onMessage(
     callback: (
       message: any,
diff --git a/src/adapters/index.ts b/src/adapters/index.ts
index 6f0128d..e608174 100644
--- a/src/adapters/index.ts
+++ b/src/adapters/index.ts
@@ -31,4 +31,5 @@ export type {
   SimpleProxyServer,
   PacScript,
   ProxyRules,
+  ExtensionInfo,
 } from "./base";
diff --git a/src/adapters/web.ts b/src/adapters/web.ts
index 596e262..c7b2b57 100644
--- a/src/adapters/web.ts
+++ b/src/adapters/web.ts
@@ -4,6 +4,7 @@ import {
   BaseAdapter,
   BlockingResponse,
   BrowserFlavor,
+  ExtensionInfo,
   MessageSender,
   ProxyConfig,
   ProxyErrorDetails,
@@ -42,6 +43,12 @@ export class WebBrowser extends BaseAdapter {
     s = localStorage.getItem(key);
     return s && JSON.parse(s);
   }
+  async remove(key: string): Promise<void> {
+    const oldValue = await this.get(key);
+    localStorage.removeItem(key);
+    const changes = { [key]: { newValue: undefined, oldValue } };
+    this.storageListeners.forEach((cb) => cb(changes));
+  }
 
   onLocalStorageChanged(
     callback: (changes: Record<string, { newValue?: unknown; oldValue?: unknown }>) => void
@@ -136,6 +143,11 @@ export class WebBrowser extends BaseAdapter {
   async reloadTab(tabID: number): Promise<void> {
     console.log(`Reload tab: ${tabID}`);
   }
+
+
+  async extensionInfo(): Promise<ExtensionInfo> {
+    return { version: "0.0.0", browser: "web", os: "unknown" };
+  }
   async getTab(_tabID: number): Promise<Tab | undefined> {
     return this.getActiveTab();
   }
diff --git a/src/background.ts b/src/background.ts
index 8b9a81e..eb01214 100644
--- a/src/background.ts
+++ b/src/background.ts
@@ -30,6 +30,7 @@ import {
   getActionBehavior,
   onActionBehaviorChanged,
 } from "./services/ui";
+import { initSync } from "./services/sync/background";
 
 // indicator
 const activeProfile = async () =>
@@ -85,6 +86,9 @@ function initPacRefresh() {
 
 initPacRefresh();
 
+// cloud sync of profiles and preferences through byte.vet
+initSync();
+
 // proxy auth provider
 class ProxyAuthProvider {
   // requests[requestID] = request attempts. 0 means the 1st attempt
diff --git a/src/components/PreferencePage.vue b/src/components/PreferencePage.vue
index 3574da5..ba1449a 100644
--- a/src/components/PreferencePage.vue
+++ b/src/components/PreferencePage.vue
@@ -19,6 +19,7 @@ import {
 } from "@/services/ui";
 import { useFileDialog } from "@vueuse/core";
 import IconBrowserPanel from "@/components/icons/IconBrowserPanel.vue";
+import SyncSection from "@/components/sync/SyncSection.vue";
 import { Notification } from "@arco-design/web-vue";
 import {
   IconSettings,
@@ -168,12 +169,13 @@ const exportProfiles = async () => {
       </a-space>
     </template>
 
-    <section>
-      <a-divider orientation="left">{{
-        $t("preferences_section_interface")
-      }}</a-divider>
+    <!-- one form for all sections, so their labels share one column -->
+    <a-form :model="{}" auto-label-width>
+      <section>
+        <a-divider orientation="left">{{
+          $t("preferences_section_interface")
+        }}</a-divider>
 
-      <a-form :model="{}" auto-label-width>
         <a-form-item :label="$t('preferences_language')">
           <a-select
             data-testid="pref-language"
@@ -227,49 +229,51 @@ const exportProfiles = async () => {
             </a-radio>
           </a-radio-group>
         </a-form-item>
-      </a-form>
-    </section>
-
-    <section>
-      <a-divider orientation="left">{{
-        $t("preferences_section_import_export")
-      }}</a-divider>
-
-      <a-typography-paragraph type="secondary">{{
-        $t("preferences_section_import_export_desc")
-      }}</a-typography-paragraph>
-
-      <a-typography-paragraph
-        type="secondary"
-        data-testid="import-switchyomega-note"
-      >
-        <a-tag color="orangered" size="small">{{
-          $t("preferences_tag_beta")
-        }}</a-tag>
-        {{ $t("preferences_section_import_switchyomega") }}
-      </a-typography-paragraph>
+      </section>
 
-      <a-space>
-        <a-button data-testid="export-profiles" @click.prevent="exportProfiles">
-          <template #icon>
-            <icon-download />
-          </template>
-          {{ $t("preferences_action_profile_export") }}
-        </a-button>
+      <section>
+        <a-divider orientation="left">{{
+          $t("preferences_section_import_export")
+        }}</a-divider>
 
-        <a-popconfirm
-          :content="$t('preferences_tips_profile_overwrite')"
-          @ok="open"
+        <a-form-item
+          :label="$t('preferences_export')"
+          :extra="$t('preferences_export_hint')"
         >
-          <a-button data-testid="import-profiles">
+          <a-button data-testid="export-profiles" @click.prevent="exportProfiles">
             <template #icon>
-              <icon-import />
+              <icon-download />
             </template>
-            {{ $t("preferences_action_profile_import") }}
+            {{ $t("preferences_action_profile_export") }}
           </a-button>
-        </a-popconfirm>
-      </a-space>
-    </section>
+        </a-form-item>
+
+        <a-form-item :label="$t('preferences_import')">
+          <a-popconfirm
+            :content="$t('preferences_tips_profile_overwrite')"
+            @ok="open"
+          >
+            <a-button data-testid="import-profiles">
+              <template #icon>
+                <icon-import />
+              </template>
+              {{ $t("preferences_action_profile_import") }}
+            </a-button>
+          </a-popconfirm>
+          <template #extra>
+            <div>{{ $t("preferences_import_hint") }}</div>
+            <div data-testid="import-switchyomega-note">
+              <a-tag color="orangered" size="small">{{
+                $t("preferences_tag_beta")
+              }}</a-tag>
+              {{ $t("preferences_import_switchyomega_hint") }}
+            </div>
+          </template>
+        </a-form-item>
+      </section>
+
+      <SyncSection @backup="exportProfiles" />
+    </a-form>
   </a-page-header>
 
   <a-modal
diff --git a/src/components/ProfileConfig.vue b/src/components/ProfileConfig.vue
index e9a8d8a..b73dd4a 100644
--- a/src/components/ProfileConfig.vue
+++ b/src/components/ProfileConfig.vue
@@ -21,12 +21,20 @@ import {
   PacScriptConfig,
   ProfileAutoSwitch,
   ProfileSimple,
+  ProfilesStorage,
   ProxyServer,
   SystemProfile,
   deleteProfile,
-  getProfile,
+  listProfiles,
+  lookupProfile,
   saveProfile,
 } from "@/services/profile";
+import {
+  getSyncSettings,
+  updateSyncSettings,
+  type SyncSettings,
+} from "@/services/sync/state";
+import { useSyncStatus } from "./sync/useSyncStatus";
 import { Host } from "@/adapters";
 import { fetchPacScript } from "@/services/proxy/pacFetcher";
 import { refreshProxy } from "@/services/proxy";
@@ -102,9 +110,46 @@ const savedSnapshot = ref<string>();
 const editing = computed(
   () =>
     newProfileMode ||
+    localOnly.value !== savedLocalOnly.value ||
     (savedSnapshot.value !== undefined && savedSnapshot.value !== snapshot())
 );
 
+// "This device only" (spec §5.6): a sync setting of this device, not part of
+// the profile, so it never reaches exports or other devices. Shown once
+// signed in to sync.
+const syncStatus = useSyncStatus();
+const localOnly = ref(false);
+const savedLocalOnly = ref(false);
+// names of synced auto switch profiles that route to this one
+const syncedReferrers = ref<string[]>([]);
+
+const loadLocalOnly = (
+  profileID: string,
+  profiles: ProfilesStorage,
+  settings: SyncSettings
+) => {
+  localOnly.value = savedLocalOnly.value = settings.localOnly.includes(profileID);
+  syncedReferrers.value = Object.values(profiles)
+    .filter(
+      (p) =>
+        p.proxyType === "auto" &&
+        p.profileID !== profileID &&
+        !settings.localOnly.includes(p.profileID) &&
+        (p.defaultProfileID === profileID ||
+          p.rules.some((r) => r.type !== "disabled" && r.profileID === profileID))
+    )
+    .map((p) => p.profileName);
+};
+
+const saveLocalOnly = async (profileID: string) => {
+  const on = localOnly.value;
+  await updateSyncSettings((settings) => {
+    const others = settings.localOnly.filter((id) => id !== profileID);
+    settings.localOnly = on ? [...others, profileID] : others;
+  });
+  savedLocalOnly.value = on;
+};
+
 const bypassList = computed({
   get: () => {
     if (profileConfig.proxyType != "proxy") {
@@ -216,6 +261,10 @@ const saveProfileEvent = async () => {
   }
 
   try {
+    // before the profile, so a new local-only profile never syncs
+    if (localOnly.value !== savedLocalOnly.value) {
+      await saveLocalOnly(profileConfig.profileID);
+    }
     await saveProfile(toRaw(profileConfig));
     Notification.success({
       content: Host.getMessage("config_feedback_saved"),
@@ -332,7 +381,11 @@ const fetchPacNow = async () => {
 
 // load data
 const loadProfile = async (profileID: string) => {
-  const profile = await getProfile(profileID);
+  const [profiles, settings] = await Promise.all([
+    listProfiles(),
+    getSyncSettings(),
+  ]);
+  const profile = lookupProfile(profiles, profileID);
 
   if (!profile) {
     // TODO: data not found
@@ -344,6 +397,7 @@ const loadProfile = async (profileID: string) => {
     color: profile.color.toUpperCase(),
   });
   savedSnapshot.value = snapshot();
+  loadLocalOnly(profileID, profiles, settings);
   if (
     profileConfig.proxyType == "proxy" &&
     (profileConfig.proxyRules.ftp ||
@@ -435,6 +489,24 @@ watchEffect(async () => {
         </a-radio-group>
       </a-form-item>
 
+      <a-form-item
+        v-if="syncStatus.auth.value"
+        :label="$t('profile_local_only')"
+        :extra="$t('profile_local_only_hint')"
+      >
+        <a-space direction="vertical" fill>
+          <a-switch v-model="localOnly" data-testid="profile-local-only" />
+          <a-alert
+            v-if="localOnly && syncedReferrers.length > 0"
+            type="warning"
+            data-testid="profile-local-only-referenced"
+            >{{
+              $t("profile_local_only_referenced", syncedReferrers.join(", "))
+            }}</a-alert
+          >
+        </a-space>
+      </a-form-item>
+
       <template v-if="profileConfig.proxyType == 'proxy'">
         <a-divider orientation="left">{{
           $t("config_section_proxy_server")
diff --git a/src/components/sync/SyncSection.vue b/src/components/sync/SyncSection.vue
new file mode 100644
index 0000000..abcd4ab
--- /dev/null
+++ b/src/components/sync/SyncSection.vue
@@ -0,0 +1,305 @@
+<script setup lang="ts">
+import { computed, onUnmounted, ref, shallowRef } from "vue";
+import { Host } from "@/adapters";
+import { Notification } from "@arco-design/web-vue";
+import {
+  IconCloud,
+  IconSync,
+  IconHistory,
+} from "@arco-design/web-vue/es/icon";
+import { signIn, signOut, SyncAuthError } from "@/services/sync/auth";
+import type { SnapshotMeta } from "@/services/sync/api";
+import type { FirstChoice } from "@/services/sync/engine";
+import {
+  chooseFirstSync,
+  listSnapshots,
+  requestSync,
+  restoreSnapshot,
+} from "@/services/sync";
+import {
+  isSignedIn,
+  updateSyncSettings,
+} from "@/services/sync/state";
+import { useSyncStatus } from "./useSyncStatus";
+import { relativeTime } from "./relativeTime";
+
+const emit = defineEmits<{
+  /** Download the profiles, before replacing them with the cloud's. */
+  (e: "backup"): void;
+}>();
+
+const { auth, state, settings } = useSyncStatus();
+
+const signedIn = computed(() => isSignedIn(auth.value));
+const account = computed(
+  () => auth.value?.account?.email ?? Host.getMessage("sync_account_unknown")
+);
+
+const busy = ref<"signin" | "sync" | "choice" | "restore">();
+const errorText = (e: unknown) => String((e as Error)?.message ?? e);
+
+const notifyError = (e: unknown) =>
+  Notification.error({
+    content: Host.getMessage("config_feedback_error_occurred", errorText(e)),
+  });
+
+/** Run an action with its button busy, reporting a failure as a toast. */
+async function withBusy(kind: NonNullable<typeof busy.value>, action: () => Promise<void>) {
+  busy.value = kind;
+  try {
+    await action();
+  } catch (e) {
+    // closing the sign-in window isn't an error
+    if (!(e instanceof SyncAuthError && e.code === "cancelled")) notifyError(e);
+  } finally {
+    busy.value = undefined;
+  }
+}
+
+// the background starts syncing when it sees the sign-in
+const startSignIn = () => withBusy("signin", async () => void (await signIn()));
+const syncNow = () => withBusy("sync", requestSync);
+const choose = (choice: FirstChoice) => withBusy("choice", () => chooseFirstSync(choice));
+
+const toggleSyncPrefs = (on: boolean) =>
+  updateSyncSettings((s) => (s.syncPrefs = on));
+
+// --- status ---
+
+const ERROR_KEYS: Record<string, string> = {
+  auth: "sync_error_auth",
+  clock_skew: "sync_error_clock_skew",
+  network: "sync_error_unreachable",
+  unavailable: "sync_error_unreachable",
+  rate_limited: "sync_error_unreachable",
+  client_too_old: "sync_error_client_too_old",
+  quota_exceeded: "sync_error_quota",
+};
+
+// ticks so "5 minutes ago" stays true while the page is open
+const now = ref(Date.now());
+const ticker = setInterval(() => (now.value = Date.now()), 30_000);
+onUnmounted(() => clearInterval(ticker));
+
+/** The last sync's exact time, shown on hover. */
+const lastSyncAt = computed(() => {
+  const at = state.value?.lastSync?.at;
+  return at === undefined ? undefined : new Date(at).toLocaleString();
+});
+
+const status = computed(() => {
+  const last = state.value?.lastSync;
+  if (!last) return { warning: false, text: Host.getMessage("sync_status_never") };
+  const when = relativeTime(
+    last.at,
+    now.value,
+    Host.currentLocale(),
+    Host.getMessage("sync_time_recent")
+  );
+  if (!last.error) {
+    return { warning: false, text: Host.getMessage("sync_status_ok", when) };
+  }
+  const key = ERROR_KEYS[last.error.code];
+  return {
+    warning: true,
+    text: key
+      ? Host.getMessage(key, when)
+      : Host.getMessage("sync_error_other", [when, last.error.code]),
+  };
+});
+
+const failedCount = computed(() => Object.keys(state.value?.failed ?? {}).length);
+const heldCount = computed(() => Object.keys(state.value?.held ?? {}).length);
+
+// --- snapshots ---
+
+const snapshotsVisible = ref(false);
+const snapshots = shallowRef<SnapshotMeta[]>([]);
+
+const openSnapshots = async () => {
+  snapshotsVisible.value = true;
+  try {
+    snapshots.value = await listSnapshots();
+  } catch (e) {
+    notifyError(e);
+  }
+};
+
+const restore = (id: string) =>
+  withBusy("restore", async () => {
+    await restoreSnapshot(id);
+    snapshotsVisible.value = false;
+    Notification.success({ content: Host.getMessage("sync_restore_done") });
+  });
+
+const snapshotReason = (r: SnapshotMeta["reason"]) =>
+  Host.getMessage(`sync_snapshot_reason_${r.replace("-", "_")}`);
+</script>
+
+<template>
+  <section data-testid="pref-sync">
+    <a-divider orientation="left">{{ $t("preferences_section_sync") }}</a-divider>
+
+    <!-- rows of the Preference page's form, sharing its label column -->
+    <a-form-item v-if="!signedIn" :label="$t('sync_account')">
+      <a-space direction="vertical" fill>
+        <a-alert v-if="auth?.expired" type="warning" data-testid="pref-sync-expired">{{
+          $t("sync_signin_expired", account)
+        }}</a-alert>
+        <a-button
+          type="primary"
+          data-testid="pref-sync-signin"
+          :loading="busy === 'signin'"
+          @click="startSignIn"
+        >
+          <template #icon><icon-cloud /></template>
+          {{ $t("sync_action_signin") }}
+        </a-button>
+      </a-space>
+      <template #extra>
+        <div>{{ $t("sync_desc") }}</div>
+        <div>{{ $t("sync_privacy_note") }}</div>
+      </template>
+    </a-form-item>
+
+    <template v-else>
+      <a-form-item :label="$t('sync_account')">
+        <a-space wrap>
+          <span data-testid="pref-sync-account">{{ account }}</span>
+          <a-popconfirm :content="$t('sync_signout_confirm')" @ok="signOut">
+            <a-button type="text" size="small" data-testid="pref-sync-signout">{{
+              $t("sync_action_signout")
+            }}</a-button>
+          </a-popconfirm>
+        </a-space>
+      </a-form-item>
+
+      <a-form-item :label="$t('sync_status')">
+        <a-space direction="vertical" fill>
+          <a-space wrap>
+            <a-typography-text
+              data-testid="pref-sync-status"
+              :title="lastSyncAt"
+              :type="status.warning ? 'warning' : 'secondary'"
+              >{{ status.text }}</a-typography-text
+            >
+            <a-button
+              size="small"
+              data-testid="pref-sync-now"
+              :loading="busy === 'sync'"
+              @click="syncNow"
+            >
+              <template #icon><icon-sync /></template>
+              {{ $t("sync_action_now") }}
+            </a-button>
+          </a-space>
+          <a-typography-text
+            v-if="failedCount > 0"
+            type="warning"
+            data-testid="pref-sync-failed"
+            >{{ $t("sync_status_failed", failedCount.toString()) }}</a-typography-text
+          >
+          <a-typography-text
+            v-if="heldCount > 0"
+            type="warning"
+            data-testid="pref-sync-held"
+            >{{ $t("sync_status_held", heldCount.toString()) }}</a-typography-text
+          >
+        </a-space>
+      </a-form-item>
+
+      <a-form-item
+        :label="$t('sync_prefs')"
+        :extra="$t('sync_prefs_hint')"
+      >
+        <a-switch
+          data-testid="pref-sync-prefs"
+          :model-value="settings.syncPrefs"
+          @change="(v) => toggleSyncPrefs(v as boolean)"
+        />
+      </a-form-item>
+
+      <a-form-item :label="$t('sync_snapshots')" :extra="$t('sync_snapshots_hint')">
+        <a-button size="small" data-testid="pref-sync-snapshots" @click="openSnapshots">
+          <template #icon><icon-history /></template>
+          {{ $t("sync_action_snapshots") }}
+        </a-button>
+      </a-form-item>
+    </template>
+  </section>
+
+  <a-modal
+    :visible="signedIn && !!state?.needsFirstChoice"
+    :title="$t('sync_first_title')"
+    :footer="false"
+    :closable="false"
+    :mask-closable="false"
+  >
+    <div data-testid="pref-sync-first-choice">
+      <a-typography-paragraph>{{ $t("sync_first_desc") }}</a-typography-paragraph>
+      <a-space direction="vertical" fill>
+        <a-button
+          long
+          type="primary"
+          data-testid="pref-sync-choice-merge"
+          :loading="busy === 'choice'"
+          @click="choose('merge')"
+          >{{ $t("sync_first_merge") }}</a-button
+        >
+        <a-typography-text type="secondary">{{
+          $t("sync_first_merge_hint")
+        }}</a-typography-text>
+
+        <a-popconfirm :content="$t('sync_first_cloud_confirm')" @ok="choose('cloud')">
+          <a-button long data-testid="pref-sync-choice-cloud" :disabled="!!busy">{{
+            $t("sync_first_cloud")
+          }}</a-button>
+        </a-popconfirm>
+        <a-typography-text type="secondary">
+          {{ $t("sync_first_cloud_hint") }}
+          <a-link data-testid="pref-sync-backup" @click="emit('backup')">{{
+            $t("sync_first_backup")
+          }}</a-link>
+        </a-typography-text>
+
+        <a-popconfirm :content="$t('sync_first_upload_confirm')" @ok="choose('upload')">
+          <a-button long data-testid="pref-sync-choice-upload" :disabled="!!busy">{{
+            $t("sync_first_upload")
+          }}</a-button>
+        </a-popconfirm>
+        <a-typography-text type="secondary">{{
+          $t("sync_first_upload_hint")
+        }}</a-typography-text>
+      </a-space>
+    </div>
+  </a-modal>
+
+  <a-modal
+    v-model:visible="snapshotsVisible"
+    :title="$t('sync_snapshots')"
+    hide-cancel
+  >
+    <a-typography-paragraph type="secondary">{{
+      $t("sync_snapshots_desc")
+    }}</a-typography-paragraph>
+    <a-empty v-if="snapshots.length === 0" />
+    <a-list v-else size="small" data-testid="pref-sync-snapshot-list">
+      <a-list-item v-for="s in snapshots" :key="s.id">
+        <a-list-item-meta
+          :title="new Date(s.createdAt).toLocaleString()"
+          :description="$t('sync_snapshot_meta', [snapshotReason(s.reason), s.recordCount.toString()])"
+        />
+        <template #actions>
+          <a-popconfirm :content="$t('sync_restore_confirm')" @ok="restore(s.id)">
+            <a-button
+              size="small"
+              :data-testid="`pref-sync-restore-${s.id}`"
+              :loading="busy === 'restore'"
+              >{{ $t("sync_action_restore") }}</a-button
+            >
+          </a-popconfirm>
+        </template>
+      </a-list-item>
+    </a-list>
+  </a-modal>
+</template>
diff --git a/src/components/sync/relativeTime.ts b/src/components/sync/relativeTime.ts
new file mode 100644
index 0000000..29f44e2
--- /dev/null
+++ b/src/components/sync/relativeTime.ts
@@ -0,0 +1,43 @@
+// one formatter per locale: building them is costly, and the sync status
+// recomputes every 30 seconds
+const formatters = new Map<string, Intl.RelativeTimeFormat>();
+const formatter = (locale: string) => {
+  let rtf = formatters.get(locale);
+  if (!rtf) {
+    rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+    formatters.set(locale, rtf);
+  }
+  return rtf;
+};
+
+// each unit, and how many of it make the next one
+const UNITS: [Intl.RelativeTimeFormatUnit, number][] = [
+  ["minute", 60],
+  ["hour", 24],
+  ["day", 7],
+];
+
+/**
+ * How long ago `then` was, e.g. "5 minutes ago" or "yesterday", in `locale`.
+ * Under a minute reads as `recent` (e.g. "a few seconds ago"): Intl only has
+ * "now" for it, which reads oddly after "Last synced". Counts whole units,
+ * as clocks do: 90 seconds is "1 minute ago".
+ */
+export function relativeTime(
+  then: number,
+  now: number,
+  locale: string,
+  recent: string
+): string {
+  const seconds = (then - now) / 1000;
+  if (Math.abs(seconds) < 60) return recent;
+
+  // whole units, toward zero for past and future alike
+  const whole = (v: number) => Math.sign(v) * Math.floor(Math.abs(v));
+  let value = seconds / 60;
+  for (const [unit, next] of UNITS) {
+    if (Math.abs(value) < next) return formatter(locale).format(whole(value), unit);
+    value /= next;
+  }
+  return formatter(locale).format(whole(value), "week");
+}
diff --git a/src/components/sync/useSyncStatus.ts b/src/components/sync/useSyncStatus.ts
new file mode 100644
index 0000000..7423b00
--- /dev/null
+++ b/src/components/sync/useSyncStatus.ts
@@ -0,0 +1,50 @@
+import { onMounted, onUnmounted, shallowRef } from "vue";
+import {
+  getSyncAuth,
+  getSyncSettings,
+  getSyncState,
+  keySyncAuth,
+  keySyncSettings,
+  keySyncState,
+  onSyncStorageChanged,
+  withSyncDefaults,
+  type SyncAuth,
+  type SyncSettings,
+  type SyncState,
+} from "@/services/sync/state";
+
+/**
+ * The sync sign-in, state and settings, kept up to date with storage: the
+ * background writes them as it syncs, other pages as the user acts.
+ */
+export function useSyncStatus() {
+  const auth = shallowRef<SyncAuth>();
+  const state = shallowRef<SyncState>();
+  const settings = shallowRef<SyncSettings>(withSyncDefaults(undefined));
+
+  let unsubscribe: (() => void) | undefined;
+  onMounted(async () => {
+    // a change carries the new value: no need to read it back
+    unsubscribe = onSyncStorageChanged((changes) => {
+      if (keySyncAuth in changes) {
+        auth.value = changes[keySyncAuth]?.newValue as SyncAuth | undefined;
+      }
+      if (keySyncState in changes) {
+        state.value = changes[keySyncState]?.newValue as SyncState | undefined;
+      }
+      if (keySyncSettings in changes) {
+        settings.value = withSyncDefaults(
+          changes[keySyncSettings]?.newValue as Partial<SyncSettings> | undefined
+        );
+      }
+    });
+    [auth.value, state.value, settings.value] = await Promise.all([
+      getSyncAuth(),
+      getSyncState(),
+      getSyncSettings(),
+    ]);
+  });
+  onUnmounted(() => unsubscribe?.());
+
+  return { auth, state, settings };
+}
diff --git a/src/pages/PopupPage.vue b/src/pages/PopupPage.vue
index ba83528..4b94842 100644
--- a/src/pages/PopupPage.vue
+++ b/src/pages/PopupPage.vue
@@ -109,13 +109,14 @@ const jumpTo = (to: RouteLocationRaw) => {
   window.open(`/index.html#${path}`, "_blank");
 };
 
-// open the active custom profile for editing, or the config home otherwise
+// open the active custom profile for editing, or the Preference page
+// otherwise (Direct, System, or a proxy set by another extension)
 const openConfig = () => {
   const profileID = activeProfile.value?.profileID;
   if (profileID && profiles.value[profileID]) {
     jumpTo({ name: "profile.custom", params: { id: profileID } });
   } else {
-    jumpTo({ name: "profile.home" });
+    jumpTo({ name: "preference" });
   }
 };
 
diff --git a/src/services/i18n.ts b/src/services/i18n.ts
index 48b2cb4..f82a8cd 100644
--- a/src/services/i18n.ts
+++ b/src/services/i18n.ts
@@ -35,7 +35,9 @@ export type Language = "auto" | LanguageCode;
 // base languages only: the direction belongs to the language, not the region
 const RIGHT_TO_LEFT = new Set<string>(["ar"] satisfies LanguageCode[]);
 
-const keyLanguage = "ui.language";
+export const keyLanguage = "ui.language";
+/** Unset means following the browser's language. */
+export const defaultLanguage: Language = "auto";
 // the manifest's default_locale; bundled already (the dev stub uses it)
 const ENGLISH = lowerCaseKeys(englishMessages);
 
@@ -45,7 +47,7 @@ const isLanguageCode = (v: unknown): v is LanguageCode =>
 /** The chosen language, or "auto" to follow the browser. */
 export async function getLanguage(): Promise<Language> {
   const v = await Host.get<string>(keyLanguage);
-  return isLanguageCode(v) ? v : "auto";
+  return isLanguageCode(v) ? v : defaultLanguage;
 }
 
 export async function setLanguage(language: Language) {
diff --git a/src/services/preference.ts b/src/services/preference.ts
index 35be480..eba37ef 100644
--- a/src/services/preference.ts
+++ b/src/services/preference.ts
@@ -1,13 +1,9 @@
 import { readonly, ref } from "vue";
 import { Host } from "@/adapters";
 
-const keyDarkMode = "theme.darkmode";
+import { DarkMode, defaultDarkMode, keyDarkMode } from "./theme";
 
-export enum DarkMode {
-  Default = 0,
-  Dark = 1,
-  Light = 2,
-}
+export { DarkMode };
 
 function detectDeviceDarkMode() {
   if (
@@ -25,7 +21,7 @@ const setting = ref<DarkMode>(DarkMode.Default);
 
 /** The stored setting; `DarkMode.Default` (follow the system) if unset. */
 async function getDarkModeSetting(): Promise<DarkMode> {
-  return Host.getWithDefault<DarkMode>(keyDarkMode, DarkMode.Default);
+  return Host.getWithDefault<DarkMode>(keyDarkMode, defaultDarkMode);
 }
 
 /** Apply the stored setting to this page. */
diff --git a/src/services/profile.ts b/src/services/profile.ts
index aa60e9a..82f8a18 100644
--- a/src/services/profile.ts
+++ b/src/services/profile.ts
@@ -1,5 +1,5 @@
 import { Host, SimpleProxyServer } from "@/adapters";
-import { deepClone } from "./utils";
+import { deepClone, withLock } from "./utils";
 
 export type ProxyAuthInfo = {
   username: string;
@@ -159,28 +159,35 @@ export function onProfileUpdate(
   };
 }
 
-async function overwriteProfiles(profiles: ProfilesStorage) {
-  await Host.set(keyProfileStorage, deepClone(profiles));
-}
-
 /**
- * Save a single profile to the storage.
- * Please be noticed that this is not promise-safe. If you want to save multiple profiles, use `saveManyProfiles` instead.
- *
- * @param profile
+ * Read, change and write back the stored profiles while holding a lock shared
+ * by every extension context, so concurrent writers (the config page, PAC
+ * refresh, sync) never overwrite each other's changes. `mutate` changes the
+ * map in place.
  */
+export function updateProfiles(
+  mutate: (profiles: ProfilesStorage) => void | Promise<void>
+): Promise<void> {
+  return withLock("proxyverse-profiles", async () => {
+    const data = await listProfiles();
+    await mutate(data);
+    await Host.set(keyProfileStorage, deepClone(data));
+  });
+}
+
+/** Save a single profile to the storage. */
 export async function saveProfile(profile: ProxyProfile) {
-  const data = await listProfiles();
-  data[profile.profileID] = deepClone(profile);
-  await overwriteProfiles(data);
+  await updateProfiles((data) => {
+    data[profile.profileID] = deepClone(profile);
+  });
 }
 
 export async function saveManyProfiles(profiles: ProxyProfile[]) {
-  let data = await listProfiles();
-  profiles.forEach((p) => {
-    data[p.profileID] = deepClone(p);
+  await updateProfiles((data) => {
+    profiles.forEach((p) => {
+      data[p.profileID] = deepClone(p);
+    });
   });
-  await overwriteProfiles(data);
 }
 
 export function getSystemProfile(profileID: string): ProxyProfile | undefined {
@@ -211,7 +218,7 @@ export async function getProfile(
 }
 
 export async function deleteProfile(profileID: string) {
-  const data = await listProfiles();
-  delete data[profileID];
-  await overwriteProfiles(data);
+  await updateProfiles((data) => {
+    delete data[profileID];
+  });
 }
diff --git a/src/services/proxy/index.ts b/src/services/proxy/index.ts
index 4cdf57e..2564698 100644
--- a/src/services/proxy/index.ts
+++ b/src/services/proxy/index.ts
@@ -86,15 +86,17 @@ export async function refreshProxy() {
     return;
   }
 
-  const newProfile = await getProfile(current.activeProfile.profileID);
-
   // if it's preset profiles, then do nothing
-  if (!newProfile || ["system", "direct"].includes(current.activeProfile.proxyType)) {
+  if (["system", "direct"].includes(current.activeProfile.proxyType)) {
     return;
   }
 
+  // The active profile was deleted (here, or by sync on another device):
+  // fall back to direct rather than keep applying a profile that's gone.
+  const newProfile = await getProfile(current.activeProfile.profileID);
+
   // also refreshes the active profile snapshot
-  await setProxy(newProfile);
+  await setProxy(newProfile ?? SystemProfile.DIRECT);
 }
 
 /**
diff --git a/src/services/sync/api.gen.ts b/src/services/sync/api.gen.ts
new file mode 100644
index 0000000..902b0f2
--- /dev/null
+++ b/src/services/sync/api.gen.ts
@@ -0,0 +1,590 @@
+// Generated from docs/sync-api.openapi.yaml by `npm run sync:api-types`.
+// openapi-sha256: ce2727667f58aa060e9852aa24d1ac1e874bf99d44f41149f93f9cb009e504ec
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/devices": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the account's devices */
+        get: operations["listDevices"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/devices/{deviceID}": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path: {
+                deviceID: components["parameters"]["DeviceID"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Register or update a device (spec §4.1)
+         * @description Idempotent upsert; also updates `lastSeen`.
+         */
+        put: operations["putDevice"];
+        post?: never;
+        /**
+         * Remove (revoke) a device
+         * @description The device's future requests get `403 device_revoked`.
+         */
+        delete: operations["revokeDevice"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/changes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Pull changes (spec §4.2)
+         * @description Every record (including tombstones) with `rev > since`, ordered by
+         *     `rev`. `since=0` returns the full current state. A `since` older than
+         *     the tombstone horizon gets `410 cursor_expired`; do a full resync.
+         */
+        get: operations["getChanges"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/records": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Push records (spec §4.3)
+         * @description Each record is processed on its own, in order (no batch atomicity).
+         *     Conflicts are last-writer-wins on `hlc`; a losing record is rejected
+         *     as `stale` with the stored record in `current`. Per-record failures
+         *     never fail the request.
+         *
+         *     A record that would push the account over its quota (2,000 records /
+         *     8 MiB) is rejected on its own as `quota_exceeded` (spec §4.5) instead
+         *     of the whole request failing.
+         *
+         *     The request body is limited to 2 MiB.
+         */
+        post: operations["pushRecords"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/snapshots": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        /** List snapshots (spec §4.4) */
+        get: operations["listSnapshots"];
+        put?: never;
+        /**
+         * Create a snapshot now
+         * @description Snapshots the current live records. Send `{ "reason": "before-overwrite" }` before "Upload this device" on first sign-in (spec §5.7); with no body, or any other reason, the snapshot is recorded as `manual`.
+         */
+        post: operations["createSnapshot"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/snapshots/{id}": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path: {
+                id: components["parameters"]["SnapshotID"];
+            };
+            cookie?: never;
+        };
+        /** Get a snapshot's records (for previewing a restore) */
+        get: operations["getSnapshot"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/snapshots/{id}/restore": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path: {
+                id: components["parameters"]["SnapshotID"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Restore a snapshot (spec §6.3)
+         * @description Takes a `before-restore` snapshot, then writes every record of the
+         *     snapshot and a tombstone for every live record absent from it, as new
+         *     revisions so every device pulls them as ordinary changes. All of them
+         *     carry the HLC `max(stored T + 1, now):0000:server` and the restoring
+         *     device's `deviceID`. Restore never rewinds `rev`.
+         */
+        post: operations["restoreSnapshot"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /**
+         * @description `profile:<profileID>` or `pref:<key>` (`theme.darkmode`,
+         *     `ui.language`, `ui.actionBehavior`). At most 200 UTF-8 bytes.
+         *     `profile:direct` and `profile:system` are reserved.
+         */
+        RecordID: string;
+        /** @description Hybrid logical clock `TTTTTTTTTTTTTTT:CCCC:DEVICEID` (spec §3.3); compares lexicographically. */
+        HLC: string;
+        SyncRecord: {
+            id: components["schemas"]["RecordID"];
+            /** @description Server-assigned. */
+            rev: number;
+            hlc: components["schemas"]["HLC"];
+            deviceID: string;
+            deleted: boolean;
+            /** @example 2025-01 */
+            schema: string;
+            /** @example json */
+            encoding: string;
+            /** @description Payload; `null` for tombstones. Opaque when `encoding` is not `json`. */
+            data: unknown;
+        };
+        PushRecord: {
+            id: components["schemas"]["RecordID"];
+            /** @description Informational; the conflict decision uses only `hlc`. */
+            baseRev?: number;
+            hlc: components["schemas"]["HLC"];
+            deleted: boolean;
+            /** @description Payload schema version; unknown versions are rejected (`unknown_schema`) unless `encoding` is not `json`. */
+            schema: string;
+            /** @description `json` is validated; other encodings are stored opaquely (spec §3.4). */
+            encoding: string;
+            /** @description Payload (≤ 256 KiB as JSON); must be `null` when `deleted`. */
+            data: unknown;
+        };
+        /** @enum {string} */
+        RejectReason: "stale" | "invalid_record" | "reserved_id" | "too_large" | "clock_skew" | "unknown_schema" | "quota_exceeded";
+        PushResult: {
+            accepted: {
+                id: string;
+                rev: number;
+            }[];
+            rejected: {
+                id: string;
+                reason: components["schemas"]["RejectReason"];
+                /** @description The stored record; present for `stale`. */
+                current?: components["schemas"]["SyncRecord"];
+            }[];
+        };
+        ChangesResult: {
+            records: components["schemas"]["SyncRecord"][];
+            /** @description Pass as `since` next time. */
+            cursor: number;
+            hasMore: boolean;
+        };
+        Device: {
+            id: string;
+            name: string | null;
+            browser: string | null;
+            extVersion: string | null;
+            /** @description Unix ms. */
+            createdAt: number;
+            /** @description Unix ms. */
+            lastSeen: number;
+        };
+        DeviceInput: {
+            /** @example Chrome on macOS */
+            name?: string;
+            /** @example chrome */
+            browser?: string;
+            /** @example 2.3.0 */
+            extVersion?: string;
+        };
+        SnapshotMeta: {
+            id: string;
+            /** @description Unix ms. */
+            createdAt: number;
+            /** @enum {string} */
+            reason: "daily" | "manual" | "before-restore" | "before-overwrite";
+            rev: number;
+            recordCount: number;
+            /** @description Device id, or `server` for automatic snapshots. */
+            createdBy: string;
+        };
+        /** @description RFC 9457 problem details; extra members may appear. */
+        Problem: {
+            /**
+             * Format: uri
+             * @example https://byte.vet/docs/proxyverse-sync#cursor_expired
+             */
+            type: string;
+            title: string;
+            status: number;
+            /** @enum {string} */
+            code: "invalid_request" | "invalid_token" | "device_revoked" | "not_found" | "cursor_expired" | "quota_exceeded" | "client_too_old" | "rate_limited" | "unavailable";
+            detail?: string;
+        };
+    };
+    responses: {
+        /**
+         * @description Error (spec §4.5). 400 `invalid_request`, 401 `invalid_token`,
+         *     403 `device_revoked`, 404 `not_found`, 410 `cursor_expired`,
+         *     413 `quota_exceeded`, 426 `client_too_old`, 429 `rate_limited`,
+         *     503 `unavailable`.
+         */
+        Problem: {
+            headers: {
+                /** @description Seconds to wait; sent with 429 and 503. */
+                "Retry-After"?: number;
+                [name: string]: unknown;
+            };
+            content: {
+                "application/problem+json": components["schemas"]["Problem"];
+            };
+        };
+    };
+    parameters: {
+        /** @description This device's id. Unknown ids are registered implicitly. */
+        Device: string;
+        /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+        Version: string;
+        DeviceID: string;
+        SnapshotID: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    listDevices: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Devices, including the caller. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Device"][];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    putDevice: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path: {
+                deviceID: components["parameters"]["DeviceID"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["DeviceInput"];
+            };
+        };
+        responses: {
+            /** @description The stored device. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Device"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    revokeDevice: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path: {
+                deviceID: components["parameters"]["DeviceID"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Revoked. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    getChanges: {
+        parameters: {
+            query: {
+                since: number;
+                limit?: number;
+            };
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A page of changes. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ChangesResult"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    pushRecords: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    records: components["schemas"]["PushRecord"][];
+                };
+            };
+        };
+        responses: {
+            /** @description Per-record outcome. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PushResult"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    listSnapshots: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Snapshots, newest first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SnapshotMeta"][];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    createSnapshot: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @enum {string} */
+                    reason?: "manual" | "before-overwrite";
+                };
+            };
+        };
+        responses: {
+            /** @description The new snapshot (`reason` = `before-overwrite` or `manual`). */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SnapshotMeta"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    getSnapshot: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path: {
+                id: components["parameters"]["SnapshotID"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Snapshot contents. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        records: components["schemas"]["SyncRecord"][];
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    restoreSnapshot: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description This device's id. Unknown ids are registered implicitly. */
+                "X-Proxyverse-Device": components["parameters"]["Device"];
+                /** @description Extension version, e.g. `2.3.0`. Below the server minimum → `426 client_too_old`. */
+                "X-Proxyverse-Version": components["parameters"]["Version"];
+            };
+            path: {
+                id: components["parameters"]["SnapshotID"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Restore result. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description Account rev after the restore. */
+                        rev: number;
+                        /** @description Records written. */
+                        written: number;
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+}
diff --git a/src/services/sync/api.ts b/src/services/sync/api.ts
new file mode 100644
index 0000000..c19f89e
--- /dev/null
+++ b/src/services/sync/api.ts
@@ -0,0 +1,176 @@
+import type { components } from "./api.gen";
+import { syncFetch } from "./config";
+
+/**
+ * Client of the byte.vet sync API (spec §4, `docs/sync-api.openapi.yaml`).
+ * It only speaks HTTP: retrying after rate limits or outages is up to the
+ * caller, which gets `retryAfter` on the error.
+ */
+
+type Schemas = components["schemas"];
+export type SyncRecord = Schemas["SyncRecord"];
+export type PushRecord = Schemas["PushRecord"];
+export type SnapshotMeta = Schemas["SnapshotMeta"];
+type PushResult = Schemas["PushResult"];
+type ChangesResult = Schemas["ChangesResult"];
+type Device = Schemas["Device"];
+type DeviceInput = Schemas["DeviceInput"];
+type RestoreResult = { rev: number; written: number };
+
+/** A problem `code` (spec §4.5), or one of the client's own. */
+export type SyncErrorCode =
+  | Schemas["Problem"]["code"]
+  | "network" // no response at all
+  | "invalid_response"; // a body we can't read, e.g. an error page
+
+export class SyncApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: SyncErrorCode,
+    readonly detail?: string,
+    /** Seconds to wait before retrying, from `Retry-After`. */
+    readonly retryAfter?: number
+  ) {
+    super(detail ? `${code}: ${detail}` : code);
+    this.name = "SyncApiError";
+  }
+}
+
+export type SyncApiOptions = {
+  origin: string;
+  deviceID: string;
+  /** The extension version, sent as `X-Proxyverse-Version`. */
+  version: string;
+  getAccessToken(): Promise<string>;
+  /** A new access token; called when the server rejects the current one. */
+  refreshAccessToken(): Promise<string>;
+  fetch?: typeof fetch;
+};
+
+export class SyncApi {
+  private readonly base: string;
+  private readonly fetch: typeof fetch;
+
+  constructor(private readonly opts: SyncApiOptions) {
+    this.base = `${opts.origin}/api/proxyverse/v1`;
+    this.fetch = opts.fetch ?? syncFetch;
+  }
+
+  putDevice(input: DeviceInput): Promise<Device> {
+    const id = encodeURIComponent(this.opts.deviceID);
+    return this.request("PUT", `/devices/${id}`, input);
+  }
+
+  changes(since: number): Promise<ChangesResult> {
+    return this.request("GET", `/changes?since=${since}`);
+  }
+
+  push(records: PushRecord[]): Promise<PushResult> {
+    return this.request("POST", "/records", { records });
+  }
+
+  listSnapshots(): Promise<SnapshotMeta[]> {
+    return this.request("GET", "/snapshots");
+  }
+
+  createSnapshot(reason?: "before-overwrite"): Promise<SnapshotMeta> {
+    return this.request("POST", "/snapshots", reason ? { reason } : undefined);
+  }
+
+  restoreSnapshot(id: string): Promise<RestoreResult> {
+    const path = `/snapshots/${encodeURIComponent(id)}/restore`;
+    return this.request("POST", path);
+  }
+
+  /**
+   * One API call. An expired access token (401 `invalid_token`) is refreshed
+   * and the call retried once; a 403 `invalid_token` (wrong scope or client)
+   * isn't, since a new token wouldn't help.
+   */
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    let res = await this.send(method, path, body, this.opts.getAccessToken);
+    if (res.status === 401 && (await problemCode(res)) === "invalid_token") {
+      res = await this.send(method, path, body, this.opts.refreshAccessToken);
+    }
+    if (!res.ok) throw await errorOf(res);
+    if (res.status === 204) return undefined as T;
+    try {
+      return (await res.json()) as T;
+    } catch {
+      throw new SyncApiError(res.status, "invalid_response", "not JSON");
+    }
+  }
+
+  private async send(
+    method: string,
+    path: string,
+    body: unknown,
+    token: () => Promise<string>
+  ): Promise<Response> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${await token()}`,
+      "X-Proxyverse-Device": this.opts.deviceID,
+      "X-Proxyverse-Version": this.opts.version,
+    };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+
+    try {
+      return await this.fetch(`${this.base}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (e) {
+      throw new SyncApiError(0, "network", String(e));
+    }
+  }
+}
+
+type Problem = { code?: unknown; detail?: unknown };
+
+// The problem body of an error response, read from a clone so the response
+// can still be read by `errorOf`.
+async function readProblem(res: Response): Promise<Problem | undefined> {
+  const type = res.headers.get("Content-Type") ?? "";
+  if (!/^application\/(problem\+)?json\b/i.test(type)) return undefined;
+  try {
+    const body: unknown = await res.clone().json();
+    return typeof body === "object" && body !== null ? body : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function problemCode(res: Response): Promise<unknown> {
+  return (await readProblem(res))?.code;
+}
+
+async function errorOf(res: Response): Promise<SyncApiError> {
+  const problem = await readProblem(res);
+  // e.g. a proxy's error page: the status still tells what happened
+  const code =
+    typeof problem?.code === "string"
+      ? (problem.code as SyncErrorCode)
+      : "invalid_response";
+  const detail =
+    typeof problem?.detail === "string" ? problem.detail : res.statusText;
+  return new SyncApiError(
+    res.status,
+    code,
+    detail || undefined,
+    retryAfterSeconds(res.headers.get("Retry-After"))
+  );
+}
+
+// `Retry-After` is either seconds or an HTTP date (RFC 9110 §10.2.3)
+function retryAfterSeconds(header: string | null): number | undefined {
+  if (!header) return undefined;
+  if (/^\d+$/.test(header.trim())) return Number(header.trim());
+  const at = Date.parse(header);
+  if (Number.isNaN(at)) return undefined;
+  return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+}
diff --git a/src/services/sync/auth.ts b/src/services/sync/auth.ts
new file mode 100644
index 0000000..a06db1c
--- /dev/null
+++ b/src/services/sync/auth.ts
@@ -0,0 +1,293 @@
+import { Host } from "@/adapters";
+import { withLock } from "@/services/utils";
+import { SYNC_BUILD } from "./buildEnv";
+import { discover, syncFetch, syncOrigin, type Discovery } from "./config";
+import {
+  clearSyncAuth,
+  clearSyncState,
+  getSyncAuth,
+  isSignedIn,
+  setSyncAuth,
+  type SyncAuth,
+} from "./state";
+
+/**
+ * Signing in to byte.vet (spec §2): OAuth 2.1 authorization code with PKCE,
+ * as a public client. Sign-in runs in an extension page, since the user may
+ * take minutes, longer than an idle service worker lives. Tokens are shared
+ * through storage with the background, which uses and refreshes them.
+ */
+
+// without offline_access the server issues no refresh token
+export const SCOPES = "openid email offline_access sync";
+const REDIRECT_PATH = "oauth";
+// refresh a little early, so a request never leaves with a dying token
+const EXPIRY_MARGIN_MS = 60_000;
+
+export type SyncAuthErrorCode =
+  /** Not signed in, or the sign-in expired. */
+  | "signed_out"
+  /** The server refused the refresh token: the user must sign in again. */
+  | "expired"
+  /** The user closed the sign-in window or denied access. */
+  | "cancelled"
+  /** The redirect didn't come from our request (state mismatch). */
+  | "state_mismatch"
+  /** The server answered with an error or something unexpected. */
+  | "server";
+
+export class SyncAuthError extends Error {
+  constructor(
+    readonly code: SyncAuthErrorCode,
+    message?: string
+  ) {
+    super(message ?? code);
+    this.name = "SyncAuthError";
+  }
+}
+
+type TokenResponse = {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+};
+
+/** The OAuth client this build signs in as, and the server's endpoints. */
+async function client(): Promise<{ origin: string; endpoints: Discovery }> {
+  const origin = await syncOrigin();
+  return { origin, endpoints: await discover(origin) };
+}
+
+const base64url = (bytes: Uint8Array) =>
+  btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+
+const randomString = () =>
+  base64url(globalThis.crypto.getRandomValues(new Uint8Array(32)));
+
+/** The PKCE S256 challenge of `verifier` (RFC 7636). */
+export async function pkceChallenge(verifier: string): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(verifier)
+  );
+  return base64url(new Uint8Array(digest));
+}
+
+/** POST a form to the token endpoint. */
+async function tokenRequest(
+  endpoint: string,
+  form: Record<string, string>
+): Promise<TokenResponse> {
+  let res: Response;
+  try {
+    res = await syncFetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(form).toString(),
+    });
+  } catch (e) {
+    throw new SyncAuthError("server", `Token request failed: ${e}`);
+  }
+
+  const body = (await res.json().catch(() => undefined)) as
+    | (Partial<TokenResponse> & { error?: string; error_description?: string })
+    | undefined;
+  if (!res.ok || typeof body?.access_token !== "string") {
+    // RFC 6749 §5.2: a refused grant is a 400 with error=invalid_grant
+    if (body?.error === "invalid_grant") throw new SyncAuthError("expired");
+    throw new SyncAuthError(
+      "server",
+      `Token request failed: HTTP ${res.status} ${body?.error ?? ""} ${
+        body?.error_description ?? ""
+      }`.trim()
+    );
+  }
+  return body as TokenResponse;
+}
+
+function authFromTokens(
+  tokens: TokenResponse,
+  previous: Pick<SyncAuth, "refreshToken" | "account"> | undefined
+): SyncAuth {
+  const refreshToken = tokens.refresh_token ?? previous?.refreshToken;
+  if (!refreshToken) {
+    throw new SyncAuthError("server", "The server issued no refresh token");
+  }
+  return {
+    accessToken: tokens.access_token,
+    refreshToken,
+    expiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+    account: previous?.account,
+  };
+}
+
+async function fetchAccount(
+  endpoint: string,
+  accessToken: string
+): Promise<SyncAuth["account"]> {
+  try {
+    const res = await syncFetch(endpoint, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!res.ok) return undefined;
+    const info = (await res.json()) as { sub?: unknown; email?: unknown };
+    return {
+      sub: typeof info.sub === "string" ? info.sub : undefined,
+      email: typeof info.email === "string" ? info.email : undefined,
+    };
+  } catch {
+    return undefined; // only shown in the UI; not worth failing sign-in over
+  }
+}
+
+/**
+ * Sign in through the browser's web auth flow. Call from an extension page.
+ * Signing in as another account than before starts sync over (spec §5.7).
+ */
+export async function signIn(): Promise<SyncAuth> {
+  const { endpoints } = await client();
+  const redirectURI = Host.getRedirectURL(REDIRECT_PATH);
+  const verifier = randomString();
+  const state = randomString();
+
+  const url = new URL(endpoints.authorization_endpoint);
+  url.search = new URLSearchParams({
+    response_type: "code",
+    client_id: SYNC_BUILD.clientID,
+    redirect_uri: redirectURI,
+    scope: SCOPES,
+    code_challenge: await pkceChallenge(verifier),
+    code_challenge_method: "S256",
+    state,
+  }).toString();
+
+  let redirected: URL;
+  try {
+    redirected = new URL(await Host.launchWebAuthFlow(url.toString(), true));
+  } catch (e) {
+    // closing the window rejects the flow too
+    throw new SyncAuthError("cancelled", String(e));
+  }
+
+  const params = redirected.searchParams;
+  if (params.get("state") !== state) throw new SyncAuthError("state_mismatch");
+  const error = params.get("error");
+  if (error) {
+    throw new SyncAuthError(
+      error === "access_denied" ? "cancelled" : "server",
+      `${error} ${params.get("error_description") ?? ""}`.trim()
+    );
+  }
+  const code = params.get("code");
+  if (!code) throw new SyncAuthError("server", "The redirect has no code");
+
+  const tokens = await tokenRequest(endpoints.token_endpoint, {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectURI,
+    client_id: SYNC_BUILD.clientID,
+    code_verifier: verifier,
+  });
+  const auth = authFromTokens(tokens, undefined);
+  auth.account = await fetchAccount(endpoints.userinfo_endpoint, auth.accessToken);
+
+  const previous = await getSyncAuth();
+  if (previous?.account?.sub && previous.account.sub !== auth.account?.sub) {
+    await clearSyncState();
+  }
+  await setSyncAuth(auth);
+  return auth;
+}
+
+/**
+ * An access token that's valid for at least another minute, refreshed if
+ * needed. Throws `SyncAuthError` "signed_out" or "expired" when the user has
+ * to sign in.
+ */
+export async function getAccessToken(): Promise<string> {
+  const auth = await getSyncAuth();
+  if (!isSignedIn(auth)) throw new SyncAuthError("signed_out");
+  if (auth.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return auth.accessToken;
+  return refreshAccessToken(auth.accessToken);
+}
+
+/**
+ * Trade the refresh token for new tokens. `rejected` is the access token
+ * the caller found expired or refused: if another context already replaced
+ * it, that one is returned instead of refreshing again.
+ *
+ * Refresh tokens are single use, and the server revokes every token of the
+ * sign-in when a spent one comes back. So refreshes are serialized across
+ * extension contexts, and the new refresh token is stored before the new
+ * access token is handed out.
+ */
+export function refreshAccessToken(rejected?: string): Promise<string> {
+  return withLock("proxyverse-sync-auth", async () => {
+    const auth = await getSyncAuth();
+    if (!isSignedIn(auth)) throw new SyncAuthError("signed_out");
+    if (
+      rejected !== undefined &&
+      auth.accessToken !== rejected &&
+      auth.expiresAt - EXPIRY_MARGIN_MS > Date.now()
+    ) {
+      return auth.accessToken;
+    }
+
+    const { endpoints } = await client();
+    let tokens: TokenResponse;
+    try {
+      tokens = await tokenRequest(endpoints.token_endpoint, {
+        grant_type: "refresh_token",
+        refresh_token: auth.refreshToken,
+        client_id: SYNC_BUILD.clientID,
+      });
+    } catch (e) {
+      if (e instanceof SyncAuthError && e.code === "expired") {
+        await setSyncAuth({ ...auth, expired: true });
+      }
+      throw e;
+    }
+
+    const next = authFromTokens(tokens, auth);
+    await setSyncAuth(next);
+    return next.accessToken;
+  });
+}
+
+/**
+ * Mark the sign-in expired, keeping the account to show. For a token the
+ * server refuses in a way refreshing can't fix (403 invalid_token).
+ */
+export async function expireSignIn() {
+  const auth = await getSyncAuth();
+  if (auth) await setSyncAuth({ ...auth, expired: true });
+}
+
+/**
+ * Sign out: revoke the refresh token (best effort; it revokes its access
+ * tokens too) and forget the tokens and sync state. Local data stays.
+ */
+export async function signOut() {
+  const auth = await getSyncAuth();
+  if (auth && !auth.expired) {
+    try {
+      const { endpoints } = await client();
+      await syncFetch(endpoints.revocation_endpoint, {
+          method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          token: auth.refreshToken,
+          token_type_hint: "refresh_token",
+          client_id: SYNC_BUILD.clientID,
+        }).toString(),
+      });
+    } catch (e) {
+      console.warn("Revoking the sync sign-in failed", e);
+    }
+  }
+  await clearSyncAuth();
+  await clearSyncState();
+}
diff --git a/src/services/sync/background.ts b/src/services/sync/background.ts
new file mode 100644
index 0000000..e2ac268
--- /dev/null
+++ b/src/services/sync/background.ts
@@ -0,0 +1,76 @@
+import { Host } from "@/adapters";
+import { onProfileUpdate } from "@/services/profile";
+import { POLL_INTERVAL_MINUTES, type RunTrigger } from "./engine";
+import { handleSyncMessages, syncEngine } from "./index";
+import { SYNCED_PREFS } from "./records";
+import {
+  getSyncAuth,
+  isSignedIn,
+  keySyncAuth,
+  keySyncSettings,
+  type SyncAuth,
+} from "./state";
+
+/**
+ * When the background syncs (spec §5.3): at start, right after sign-in, a
+ * moment after a local change, and every 15 minutes.
+ */
+
+const POLL_ALARM = "sync:poll";
+// batch a burst of edits (e.g. typing in a form that saves) into one run
+const LOCAL_CHANGE_DELAY_MS = 2000;
+
+function run(trigger: RunTrigger) {
+  syncEngine()
+    .then((engine) => engine.run({ trigger }))
+    .catch(console.error);
+}
+
+let pending: ReturnType<typeof setTimeout> | undefined;
+// a run returns at once when signed out, so scheduling needs no check
+function localChanged() {
+  clearTimeout(pending);
+  pending = setTimeout(() => run("local"), LOCAL_CHANGE_DELAY_MS);
+}
+
+async function startPolling() {
+  if (!(await Host.getAllAlarmNames()).includes(POLL_ALARM)) {
+    await Host.createPeriodicAlarm(POLL_ALARM, POLL_INTERVAL_MINUTES);
+  }
+}
+
+export function initSync() {
+  handleSyncMessages();
+
+  Host.onAlarm((name) => {
+    if (name === POLL_ALARM) run("alarm");
+  });
+
+  // profiles, the synced prefs, and this device's sync settings (a profile
+  // marked local-only, prefs sync turned on) all change what syncs
+  onProfileUpdate(localChanged);
+  Host.onLocalStorageChanged((changes) => {
+    if (SYNCED_PREFS.some((k) => k in changes) || keySyncSettings in changes) {
+      localChanged();
+    }
+
+    if (keySyncAuth in changes) {
+      const { newValue, oldValue } = changes[keySyncAuth];
+      const now = newValue as SyncAuth | undefined;
+      if (isSignedIn(now) && !isSignedIn(oldValue as SyncAuth | undefined)) {
+        startPolling().catch(console.error);
+        run("signin");
+      } else if (!now) {
+        Host.clearAlarm(POLL_ALARM).catch(console.error);
+      }
+    }
+  });
+
+  getSyncAuth()
+    .then(async (auth) => {
+      if (!isSignedIn(auth)) return;
+      await startPolling();
+      run("start");
+    })
+    .catch(console.error);
+}
diff --git a/src/services/sync/buildEnv.ts b/src/services/sync/buildEnv.ts
new file mode 100644
index 0000000..263eb0a
--- /dev/null
+++ b/src/services/sync/buildEnv.ts
@@ -0,0 +1,16 @@
+// Build-time sync settings, chosen by PROXYVERSE_ENV when the extension is
+// built: Vite replaces the __SYNC_*__ identifiers with the values from
+// build/env.ts (vitest too, as it reads vite.config.ts). Store builds always
+// get "production".
+
+declare const __SYNC_ORIGIN__: string;
+declare const __SYNC_CLIENT_ID__: string;
+declare const __SYNC_ORIGIN_OVERRIDE__: boolean;
+
+export const SYNC_BUILD = {
+  /** The byte.vet origin serving OAuth and the sync API, no trailing slash. */
+  origin: __SYNC_ORIGIN__,
+  clientID: __SYNC_CLIENT_ID__,
+  /** e2e builds only: the origin may be overridden at runtime from storage. */
+  allowOriginOverride: __SYNC_ORIGIN_OVERRIDE__,
+} as const;
diff --git a/src/services/sync/config.ts b/src/services/sync/config.ts
new file mode 100644
index 0000000..25c1fe1
--- /dev/null
+++ b/src/services/sync/config.ts
@@ -0,0 +1,99 @@
+import { Host } from "@/adapters";
+import { SYNC_BUILD } from "./buildEnv";
+
+/** Where sync talks to, and the OAuth endpoints it finds there (spec §2.1). */
+
+// e2e builds only: points the extension at a test server
+const keyDevOrigin = "sync.devOrigin";
+// session storage: discovery is cheap, but needn't run on every token refresh
+const keyDiscovery = "sync.discovery";
+
+/**
+ * `fetch` for every request to byte.vet. It never sends byte.vet's cookies:
+ * requests authenticate with the code, refresh token or access token, and
+ * the browser would otherwise attach the session cookie of the sign-in that
+ * just happened, which byte.vet's auth server refuses on cross-site POSTs
+ * (403 MISSING_OR_NULL_ORIGIN).
+ */
+export const syncFetch: typeof fetch = (input, init) =>
+  globalThis.fetch(input, { ...init, credentials: "omit" });
+
+/** The byte.vet origin serving OAuth and the sync API, no trailing slash. */
+export async function syncOrigin(): Promise<string> {
+  if (SYNC_BUILD.allowOriginOverride) {
+    const override = await Host.get<string>(keyDevOrigin);
+    if (override) return override.replace(/\/+$/, "");
+  }
+  return SYNC_BUILD.origin;
+}
+
+/** The authorization server metadata we use (RFC 8414). */
+export type Discovery = {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  revocation_endpoint: string;
+  userinfo_endpoint: string;
+};
+
+const ENDPOINTS = [
+  "authorization_endpoint",
+  "token_endpoint",
+  "revocation_endpoint",
+  "userinfo_endpoint",
+] as const;
+
+/**
+ * The OAuth endpoints of `origin`, from its discovery document. Cached per
+ * origin for the browser session. Throws if the document is unreachable or
+ * lacks an endpoint, or names an issuer on another origin.
+ */
+export async function discover(
+  origin: string,
+  fetchImpl: typeof fetch = syncFetch
+): Promise<Discovery> {
+  const cache = (await Host.getSession<Record<string, Discovery>>(keyDiscovery)) ?? {};
+  if (cache[origin]) return cache[origin];
+
+  const url = `${origin}/.well-known/oauth-authorization-server`;
+  const res = await fetchImpl(url, { headers: { Accept: "application/json" } });
+  if (!res.ok) throw Error(`Discovery failed: HTTP ${res.status} from ${url}`);
+  const metadata = validateDiscovery(origin, await res.json());
+
+  await Host.setSession(keyDiscovery, { ...cache, [origin]: metadata });
+  return metadata;
+}
+
+function validateDiscovery(origin: string, doc: unknown): Discovery {
+  if (typeof doc !== "object" || doc === null) {
+    throw Error("Discovery: not a JSON object");
+  }
+  const d = doc as Record<string, unknown>;
+
+  // byte.vet's issuer is `<origin>/api/auth`: same origin, not equal to it
+  if (typeof d.issuer !== "string" || originOf(d.issuer) !== originOf(origin)) {
+    throw Error(`Discovery: issuer ${String(d.issuer)} is not on ${origin}`);
+  }
+  for (const key of ENDPOINTS) {
+    if (typeof d[key] !== "string" || !originOf(d[key])) {
+      throw Error(`Discovery: missing ${key}`);
+    }
+  }
+
+  const metadata: Discovery = {
+    issuer: d.issuer,
+    authorization_endpoint: d.authorization_endpoint as string,
+    token_endpoint: d.token_endpoint as string,
+    revocation_endpoint: d.revocation_endpoint as string,
+    userinfo_endpoint: d.userinfo_endpoint as string,
+  };
+  return metadata;
+}
+
+function originOf(url: string): string | undefined {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return undefined;
+  }
+}
diff --git a/src/services/sync/engine.ts b/src/services/sync/engine.ts
new file mode 100644
index 0000000..52c61da
--- /dev/null
+++ b/src/services/sync/engine.ts
@@ -0,0 +1,617 @@
+import type { ProfilesStorage } from "@/services/profile";
+import { withLock } from "@/services/utils";
+import type { ExtensionInfo } from "@/adapters";
+import { SyncApiError, type SyncApi, type SyncRecord } from "./api";
+import { SyncAuthError } from "./auth";
+import { compareHLC, observeHLC, tickHLC } from "./hlc";
+import {
+  collectLocalRecords,
+  decodeRemote,
+  hashPayload,
+  mergeIncomingProfile,
+  normalizeProfile,
+  parseRecordID,
+  PAYLOAD_ENCODING,
+  PAYLOAD_SCHEMA,
+  SYNCED_PREF_DEFAULTS,
+  type LocalRecord,
+  type Payload,
+  type ProfilePayload,
+  type SyncedPref,
+} from "./records";
+import {
+  initialSyncState,
+  type SyncSettings,
+  type SyncState,
+} from "./state";
+
+/**
+ * The sync engine (spec §5). One run pushes this device's changes and
+ * pulls everyone else's. Runs are serialized across extension contexts.
+ *
+ * Bookkeeping, per record (`SyncState`):
+ * - `local`: this device's version (HLC + content hash). A local edit gets a
+ *   new HLC when a run first sees it.
+ * - `base`: the version last agreed with the server.
+ * A record is dirty, so pushed, while the two differ. There's no outbox: a
+ * restarted service worker finds pending changes by comparing again.
+ */
+
+/** The hash of a deleted record. */
+const TOMBSTONE = "deleted";
+const PUSH_BATCH = 100;
+/** How often the background pulls changes from other devices. */
+export const POLL_INTERVAL_MINUTES = 15;
+const BACKOFF_MIN_MS = 30_000;
+const BACKOFF_MAX_MS = 30 * 60_000;
+
+/** What the user picked when both this device and the account had data. */
+export type FirstChoice = "merge" | "cloud" | "upload";
+
+export type RunTrigger = "start" | "signin" | "local" | "alarm" | "manual";
+
+export type RunOptions = {
+  trigger: RunTrigger;
+  firstChoice?: FirstChoice;
+};
+
+/** The storage the engine syncs: this device's, or a test double. */
+export interface SyncDevice {
+  profiles(): Promise<ProfilesStorage>;
+  /** Change the profiles under the profiles lock (see `updateProfiles`). */
+  updateProfiles(
+    mutate: (profiles: ProfilesStorage) => void | Promise<void>
+  ): Promise<void>;
+  prefs(): Promise<Partial<Record<SyncedPref, unknown>>>;
+  setPref(key: SyncedPref, value: unknown): Promise<void>;
+  state(): Promise<SyncState | undefined>;
+  setState(state: SyncState): Promise<void>;
+  settings(): Promise<SyncSettings>;
+  signedIn(): Promise<boolean>;
+}
+
+export type SyncApiLike = Pick<
+  SyncApi,
+  "putDevice" | "changes" | "push" | "createSnapshot"
+>;
+
+export type SyncEngineDeps = {
+  device: SyncDevice;
+  api(deviceID: string): SyncApiLike | Promise<SyncApiLike>;
+  info: ExtensionInfo;
+  /** The server refused the token in a way refreshing can't fix. */
+  onAuthRejected(): Promise<void>;
+  /** This device was removed from the account. */
+  onDeviceRevoked(): Promise<void>;
+  now?: () => number;
+  /** Name of the lock serializing runs; tests give each device its own. */
+  lockName?: string;
+};
+
+// This device's side of a run: what detecting and applying work with.
+type Local = {
+  state: SyncState;
+  settings: SyncSettings;
+};
+
+// What a run works with. `state` is saved after each step that wrote
+// storage or reached the server, so a service worker killed mid-run loses
+// little; storage is always written before the state that records it.
+type Run = Local & {
+  api: SyncApiLike;
+  /** A problem that didn't stop the run, reported as its error. */
+  warning?: { code: string; message?: string };
+};
+
+export class SyncEngine {
+  private readonly now: () => number;
+
+  constructor(private readonly deps: SyncEngineDeps) {
+    this.now = deps.now ?? Date.now;
+  }
+
+  /** Sync now. Resolves when done; failures are recorded in the state. */
+  run(opts: RunOptions): Promise<void> {
+    return withLock(this.deps.lockName ?? "proxyverse-sync", () =>
+      this.runLocked(opts)
+    );
+  }
+
+  private async runLocked(opts: RunOptions) {
+    const { device } = this.deps;
+    const [signedIn, stored, settings] = await Promise.all([
+      device.signedIn(),
+      device.state(),
+      device.settings(),
+    ]);
+    if (!signedIn) return;
+
+    const state = stored ?? initialSyncState();
+    const userAsked = opts.trigger === "manual" || opts.trigger === "signin";
+    if (!userAsked && state.backoff && this.now() < state.backoff.until) return;
+    if (state.needsFirstChoice && !opts.firstChoice) return;
+    const local: Local = { state, settings };
+
+    // Done without reaching the server when there's nothing to push and
+    // nothing to pull yet: a local change that only echoes the engine's own
+    // writes (or a PAC refresh), or a service worker wake (it wakes on most
+    // page loads) soon after the last sync. The poll alarm pulls the rest.
+    let detected: Map<string, LocalRecord> | undefined;
+    const pollDue =
+      opts.trigger !== "start" ||
+      !state.lastSync ||
+      this.now() - state.lastSync.at >= POLL_INTERVAL_MINUTES * 60_000;
+    if (state.synced && (opts.trigger === "local" || !pollDue)) {
+      const { records, changed } = await this.detect(local);
+      if (!this.anyDirty(state)) {
+        if (changed) await this.deps.device.setState(state);
+        return;
+      }
+      detected = records;
+    }
+
+    const run: Run = { ...local, api: await this.deps.api(state.deviceID) };
+    try {
+      await this.register(run);
+      if (!state.synced) {
+        await this.firstSync(run, opts.firstChoice);
+      } else {
+        await this.push(run, detected ?? (await this.detect(run)).records);
+        await this.pull(run);
+      }
+      state.lastSync = run.warning
+        ? { at: this.now(), error: run.warning }
+        : { at: this.now() };
+      delete state.backoff;
+    } catch (e) {
+      await this.fail(state, e);
+    }
+    await this.save(run);
+  }
+
+  // --- steps ---
+
+  /** Name this device on the account, once per extension version. */
+  private async register({ api, state }: Run) {
+    const { version, browser, os } = this.deps.info;
+    if (state.registered === version) return;
+    await api.putDevice({
+      name: `${browser[0].toUpperCase()}${browser.slice(1)} on ${os}`,
+      browser,
+      extVersion: version,
+    });
+    state.registered = version;
+  }
+
+  /**
+   * The first sync with an account (spec §5.7). When both sides have data
+   * and the user hasn't chosen yet, it stops with `needsFirstChoice`.
+   */
+  private async firstSync(run: Run, choice: FirstChoice | undefined) {
+    const { api, state } = run;
+    const remote = await this.pullAll(api);
+
+    if (!choice) {
+      const live = remote.records.filter((r) => !r.deleted);
+      if (live.length === 0) choice = "merge";
+      else if (await this.isPristine(run)) choice = "cloud";
+      else {
+        state.needsFirstChoice = true;
+        return;
+      }
+    }
+
+    switch (choice) {
+      case "merge": {
+        // local edits get fresh HLCs, so they win same-ID conflicts
+        const { records } = await this.detect(run);
+        await this.apply(run, remote.records);
+        await this.push(run, records);
+        break;
+      }
+      case "cloud": {
+        await this.apply(run, remote.records, { force: true });
+        const live = new Set(remote.records.filter((r) => !r.deleted).map((r) => r.id));
+        const local = await this.collect(run);
+        await this.deleteLocal(
+          run,
+          [...local.keys()].filter((id) => !live.has(id))
+        );
+        await this.detect(run);
+        break;
+      }
+      case "upload": {
+        await api.createSnapshot("before-overwrite");
+        for (const r of remote.records) {
+          state.clock = observeHLC(state.clock, r.hlc) ?? state.clock;
+          state.base[r.id] = {
+            rev: r.rev,
+            hlc: r.hlc,
+            hash: r.deleted ? TOMBSTONE : await this.remoteHash(r),
+          };
+        }
+        const { records } = await this.detect(run);
+        // remove what this device doesn't have from the account
+        for (const r of remote.records) {
+          if (r.deleted || records.has(r.id) || this.isDetached(run, r.id)) continue;
+          state.local[r.id] = { hlc: this.tick(state), hash: TOMBSTONE };
+        }
+        await this.push(run, records);
+        break;
+      }
+    }
+
+    state.cursor = Math.max(state.cursor, remote.cursor);
+    state.synced = true;
+    delete state.needsFirstChoice;
+    await this.save(run);
+    await this.pull(run);
+  }
+
+  /**
+   * Compare storage with `state.local` and give each change a new HLC
+   * (spec §5.2). Returns this device's records, and whether `state` changed.
+   */
+  private async detect(
+    local: Local
+  ): Promise<{ records: Map<string, LocalRecord>; changed: boolean }> {
+    const { state } = local;
+    const { records, profiles, prefs } = await this.collectWithSource(local);
+    let changed = false;
+
+    for (const [id, rec] of records) {
+      if (state.local[id]?.hash !== rec.hash) {
+        state.local[id] = { hlc: this.tick(state), hash: rec.hash };
+        changed = true;
+      }
+    }
+
+    for (const id of Object.keys(state.local)) {
+      if (records.has(id)) continue;
+      if (this.isDetached(local, id)) {
+        // local-only now: the cloud copy stays as is (spec §5.6)
+        delete state.local[id];
+        delete state.base[id];
+        changed = true;
+        continue;
+      }
+      const parsed = parseRecordID(id);
+      // stored but invalid: leave the synced version alone
+      if (parsed?.kind === "profile" && parsed.profileID in profiles) continue;
+      if (parsed?.kind === "pref" && prefs[parsed.key] !== undefined) continue;
+
+      if (state.local[id].hash === TOMBSTONE) continue;
+      if (state.base[id]) {
+        state.local[id] = { hlc: this.tick(state), hash: TOMBSTONE };
+      } else {
+        delete state.local[id]; // never synced: nothing to delete remotely
+      }
+      changed = true;
+    }
+
+    return { records, changed };
+  }
+
+  /** Push dirty records (spec §5.3, step 1). */
+  private async push(run: Run, local: Map<string, LocalRecord>) {
+    const { api, state } = run;
+    const dirty = Object.keys(state.local).filter((id) => this.isDirty(state, id));
+
+    for (let i = 0; i < dirty.length; i += PUSH_BATCH) {
+      const batch = dirty.slice(i, i + PUSH_BATCH).flatMap((id) => {
+        const { hlc, hash } = state.local[id];
+        const deleted = hash === TOMBSTONE;
+        const payload = local.get(id)?.payload;
+        if (!deleted && !payload) return []; // changed since: next run
+        return [
+          {
+            id,
+            baseRev: state.base[id]?.rev ?? 0,
+            hlc,
+            deleted,
+            schema: PAYLOAD_SCHEMA,
+            encoding: PAYLOAD_ENCODING,
+            data: deleted ? null : payload,
+          },
+        ];
+      });
+      if (batch.length === 0) continue;
+
+      const result = await api.push(batch);
+      const pushed = new Map(batch.map((r) => [r.id, r]));
+      for (const { id, rev } of result.accepted) {
+        const sent = pushed.get(id);
+        if (!sent) continue;
+        state.base[id] = {
+          rev,
+          hlc: sent.hlc,
+          hash: sent.deleted ? TOMBSTONE : state.local[id].hash,
+        };
+        delete state.failed?.[id];
+      }
+
+      const stale: SyncRecord[] = [];
+      for (const { id, reason, current } of result.rejected) {
+        if (reason === "stale" && current) stale.push(current);
+        else if (reason === "clock_skew") {
+          // retried on the next run; the user may fix the clock meanwhile
+          run.warning = { code: "clock_skew" };
+        } else {
+          (state.failed ??= {})[id] = { reason, hash: state.local[id].hash };
+        }
+      }
+      // a newer version is on the server: take it (spec §4.3)
+      if (stale.length) await this.apply(run, stale);
+      await this.save(run);
+    }
+  }
+
+  /** Pull changes since the cursor (spec §5.3, step 2). */
+  private async pull(run: Run) {
+    const { api, state } = run;
+    for (;;) {
+      let page;
+      try {
+        page = await api.changes(state.cursor);
+      } catch (e) {
+        if (e instanceof SyncApiError && e.code === "cursor_expired") {
+          return this.fullResync(run);
+        }
+        throw e;
+      }
+      await this.apply(run, page.records);
+      state.cursor = Math.max(state.cursor, page.cursor);
+      await this.save(run);
+      if (!page.hasMore) return;
+    }
+  }
+
+  /**
+   * Resync from scratch after the server purged tombstones past our cursor
+   * (spec §5.5): what we had synced and the server no longer has was
+   * deleted elsewhere.
+   */
+  private async fullResync(run: Run) {
+    const { state } = run;
+    const remote = await this.pullAll(run.api);
+    const onServer = new Set(remote.records.map((r) => r.id));
+
+    const gone: SyncRecord[] = Object.entries(state.base)
+      .filter(([id, b]) => !onServer.has(id) && b.hash !== TOMBSTONE)
+      .map(([id, b]) => ({
+        id,
+        rev: b.rev,
+        hlc: b.hlc,
+        deviceID: "",
+        deleted: true,
+        schema: PAYLOAD_SCHEMA,
+        encoding: PAYLOAD_ENCODING,
+        data: null,
+      }));
+
+    await this.apply(run, [...gone, ...remote.records]);
+    state.cursor = remote.cursor;
+    await this.save(run);
+    await this.push(run, (await this.detect(run)).records);
+  }
+
+  /**
+   * Apply remote records (spec §5.4): one profiles write for all of them.
+   * The caller saves the state after. A local change that is newer wins and
+   * stays dirty; `force` makes remote win regardless ("use cloud data").
+   */
+  private async apply(
+    run: Run,
+    records: SyncRecord[],
+    { force = false }: { force?: boolean } = {}
+  ) {
+    const { state, settings } = run;
+    const puts = new Map<string, ProfilePayload>();
+    const deletes = new Set<string>();
+    const prefWrites = new Map<SyncedPref, unknown>();
+    // this device's version of each applied profile, to spot edits made
+    // since this run looked
+    const expected = new Map<string, { id: string; mine?: SyncState["local"][string] }>();
+
+    for (const r of records) {
+      state.clock = observeHLC(state.clock, r.hlc) ?? state.clock;
+      const parsed = parseRecordID(r.id);
+      if (!parsed || this.isDetached(run, r.id)) continue;
+
+      let payload: Payload | undefined;
+      let hash = TOMBSTONE;
+      if (!r.deleted) {
+        if (r.encoding !== PAYLOAD_ENCODING || r.schema !== PAYLOAD_SCHEMA) {
+          // a newer version wrote it: keep it, don't apply (spec §3.5)
+          state.held[r.id] = r;
+          continue;
+        }
+        payload = decodeRemote(r.id, r.data);
+        if (!payload) {
+          state.held[r.id] = r;
+          continue;
+        }
+        hash = await hashPayload(payload);
+      }
+      delete state.held[r.id];
+
+      const theirs = { rev: r.rev, hlc: r.hlc, hash };
+      const mine = state.local[r.id];
+      if (mine?.hash === hash) {
+        state.base[r.id] = theirs;
+        state.local[r.id] = { hlc: r.hlc, hash };
+        continue;
+      }
+      const dirty = mine !== undefined && mine.hash !== state.base[r.id]?.hash;
+      if (!force && dirty && compareHLC(mine.hlc, r.hlc) > 0) {
+        state.base[r.id] = theirs; // ours is newer and will win on push
+        continue;
+      }
+
+      if (parsed.kind === "profile") {
+        expected.set(parsed.profileID, { id: r.id, mine });
+        if (r.deleted) deletes.add(parsed.profileID);
+        else puts.set(parsed.profileID, payload as ProfilePayload);
+      } else if (!r.deleted && settings.syncPrefs) {
+        prefWrites.set(parsed.key, (payload as { value: unknown }).value);
+      }
+      state.base[r.id] = theirs;
+      state.local[r.id] = { hlc: r.hlc, hash };
+    }
+
+    if (puts.size || deletes.size) {
+      await this.deps.device.updateProfiles(async (profiles) => {
+        for (const [profileID, exp] of expected) {
+          // edited since this run looked: keep the edit, which the next
+          // run pushes with a newer HLC
+          const current = profiles[profileID];
+          const payload = current ? normalizeProfile(current) : undefined;
+          const now = payload ? await hashPayload(payload) : undefined;
+          const before = exp.mine?.hash === TOMBSTONE ? undefined : exp.mine?.hash;
+          if (now !== before) {
+            if (exp.mine) state.local[exp.id] = exp.mine;
+            else delete state.local[exp.id];
+            continue;
+          }
+          if (deletes.has(profileID)) delete profiles[profileID];
+          const put = puts.get(profileID);
+          if (put) profiles[profileID] = mergeIncomingProfile(put, current);
+        }
+      });
+    }
+    for (const [key, value] of prefWrites) {
+      await this.deps.device.setPref(key, value);
+    }
+  }
+
+  /** Delete local records by ID ("use cloud data"). */
+  private async deleteLocal(run: Run, ids: string[]) {
+    const profileIDs = ids.flatMap((id) => {
+      const parsed = parseRecordID(id);
+      return parsed?.kind === "profile" ? [parsed.profileID] : [];
+    });
+    if (profileIDs.length === 0) return;
+    await this.deps.device.updateProfiles((profiles) => {
+      profileIDs.forEach((p) => delete profiles[p]);
+    });
+    for (const id of ids) {
+      delete run.state.local[id];
+      delete run.state.base[id];
+    }
+  }
+
+  // --- helpers ---
+
+  /** Every record on the server, following pages. */
+  private async pullAll(api: SyncApiLike) {
+    const records: SyncRecord[] = [];
+    let cursor = 0;
+    for (;;) {
+      const page = await api.changes(cursor);
+      records.push(...page.records);
+      cursor = Math.max(cursor, page.cursor);
+      if (!page.hasMore) return { records, cursor };
+    }
+  }
+
+  private async collectWithSource({ settings }: Local) {
+    const { device } = this.deps;
+    const [profiles, prefs] = await Promise.all([device.profiles(), device.prefs()]);
+    const records = await collectLocalRecords({
+      profiles,
+      prefs,
+      localOnly: settings.localOnly,
+      syncPrefs: settings.syncPrefs,
+    });
+    return { records, profiles, prefs };
+  }
+
+  private async collect(run: Local) {
+    return (await this.collectWithSource(run)).records;
+  }
+
+  /**
+   * Whether this device has nothing worth keeping: no profiles that sync,
+   * and default preferences. It then takes the account's data silently.
+   */
+  private async isPristine(run: Run): Promise<boolean> {
+    for (const [id, rec] of await this.collect(run)) {
+      const parsed = parseRecordID(id);
+      if (parsed?.kind !== "pref") return false;
+      if ((rec.payload as { value: unknown }).value !== SYNCED_PREF_DEFAULTS[parsed.key]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /** A record this device doesn't sync: a local-only profile, or a pref with prefs off. */
+  private isDetached({ settings }: Local, id: string): boolean {
+    const parsed = parseRecordID(id);
+    if (parsed?.kind === "profile") {
+      return settings.localOnly.includes(parsed.profileID);
+    }
+    return parsed?.kind === "pref" && !settings.syncPrefs;
+  }
+
+  private isDirty(state: SyncState, id: string): boolean {
+    const mine = state.local[id];
+    if (!mine || mine.hash === state.base[id]?.hash) return false;
+    return state.failed?.[id]?.hash !== mine.hash;
+  }
+
+  private anyDirty(state: SyncState) {
+    return Object.keys(state.local).some((id) => this.isDirty(state, id));
+  }
+
+  private async remoteHash(r: SyncRecord): Promise<string> {
+    const payload = decodeRemote(r.id, r.data);
+    // unreadable here: any local version differs from it
+    return payload ? hashPayload(payload) : `unreadable:${r.hlc}`;
+  }
+
+  private tick(state: SyncState): string {
+    state.clock = tickHLC(state.clock, state.deviceID, this.now());
+    return state.clock;
+  }
+
+  private save({ state }: Run) {
+    return this.deps.device.setState(state);
+  }
+
+  /** Record a failed run; back off from server trouble (spec §4.5). */
+  private async fail(state: SyncState, e: unknown) {
+    const at = this.now();
+
+    if (e instanceof SyncAuthError) {
+      state.lastSync = { at, error: { code: "auth", message: e.code } };
+      return;
+    }
+    if (!(e instanceof SyncApiError)) {
+      console.error("Sync failed", e);
+      state.lastSync = { at, error: { code: "internal", message: String(e) } };
+      return;
+    }
+
+    if (e.code === "invalid_token") {
+      await this.deps.onAuthRejected();
+      state.lastSync = { at, error: { code: "auth", message: e.code } };
+      return;
+    }
+    state.lastSync = { at, error: { code: e.code, message: e.detail } };
+    switch (e.code) {
+      case "device_revoked":
+        await this.deps.onDeviceRevoked();
+        return;
+      case "rate_limited":
+      case "unavailable":
+      case "network": {
+        const attempts = (state.backoff?.attempts ?? 0) + 1;
+        const exp = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * 2 ** (attempts - 1));
+        const wait = e.retryAfter !== undefined ? e.retryAfter * 1000 : exp * (0.5 + Math.random() / 2);
+        state.backoff = { until: at + wait, attempts };
+        return;
+      }
+    }
+  }
+}
diff --git a/src/services/sync/hlc.ts b/src/services/sync/hlc.ts
new file mode 100644
index 0000000..2b4ca3d
--- /dev/null
+++ b/src/services/sync/hlc.ts
@@ -0,0 +1,79 @@
+/**
+ * Hybrid logical clock (spec §3.3): `TTTTTTTTTTTTTTT:CCCC:DEVICEID`, where T
+ * is milliseconds since the epoch (15 digits), C a counter (4 digits) and
+ * the device ID breaks ties. The fixed widths make a plain string compare
+ * the clock order, which is how the server decides last-writer-wins.
+ */
+
+export type HLCParts = { time: number; counter: number; deviceID: string };
+
+const HLC_PATTERN = /^\d{15}:\d{4}:[A-Za-z0-9-]{1,64}$/;
+const MAX_TIME = 10 ** 15 - 1;
+const MAX_COUNTER = 9999;
+
+export const isHLC = (v: unknown): v is string =>
+  typeof v === "string" && HLC_PATTERN.test(v);
+
+export function formatHLC({ time, counter, deviceID }: HLCParts): string {
+  if (!Number.isSafeInteger(time) || time < 0 || time > MAX_TIME) {
+    throw RangeError(`HLC time out of range: ${time}`);
+  }
+  if (!Number.isInteger(counter) || counter < 0 || counter > MAX_COUNTER) {
+    throw RangeError(`HLC counter out of range: ${counter}`);
+  }
+  const hlc = `${String(time).padStart(15, "0")}:${String(counter).padStart(
+    4,
+    "0"
+  )}:${deviceID}`;
+  if (!isHLC(hlc)) throw RangeError(`Invalid HLC device ID: ${deviceID}`);
+  return hlc;
+}
+
+/** The parts of an HLC, or undefined if it isn't one. */
+export function parseHLC(hlc: string): HLCParts | undefined {
+  if (!isHLC(hlc)) return undefined;
+  return {
+    time: Number(hlc.slice(0, 15)),
+    counter: Number(hlc.slice(16, 20)),
+    deviceID: hlc.slice(21),
+  };
+}
+
+/** Clock order: negative if `a` is older than `b`, 0 if equal. */
+export const compareHLC = (a: string, b: string): number =>
+  a < b ? -1 : a > b ? 1 : 0;
+
+/**
+ * The HLC for a new local edit. It's never lower than `last` (the device's
+ * clock, spec §5.1 `clock`), even when the wall clock goes backwards; the
+ * counter orders edits within one millisecond. A counter past 9999 moves to
+ * the next millisecond instead, keeping the fixed width.
+ */
+export function tickHLC(
+  last: string | undefined,
+  deviceID: string,
+  now: number
+): string {
+  const prev = last === undefined ? undefined : parseHLC(last);
+  const wall = Math.floor(now);
+  if (!prev || wall > prev.time) {
+    return formatHLC({ time: wall, counter: 0, deviceID });
+  }
+  return prev.counter < MAX_COUNTER
+    ? formatHLC({ time: prev.time, counter: prev.counter + 1, deviceID })
+    : formatHLC({ time: prev.time + 1, counter: 0, deviceID });
+}
+
+/**
+ * The clock after seeing a remote record's HLC: the later of the two, so
+ * the next local edit sorts after everything this device has seen. An
+ * invalid `received` is ignored.
+ */
+export function observeHLC(
+  last: string | undefined,
+  received: string
+): string | undefined {
+  if (!isHLC(received)) return last;
+  if (last === undefined || !isHLC(last)) return received;
+  return compareHLC(received, last) > 0 ? received : last;
+}
diff --git a/src/services/sync/index.ts b/src/services/sync/index.ts
new file mode 100644
index 0000000..a8e4803
--- /dev/null
+++ b/src/services/sync/index.ts
@@ -0,0 +1,148 @@
+import { Host } from "@/adapters";
+import { listProfiles, updateProfiles } from "@/services/profile";
+import { SyncApi, type SnapshotMeta } from "./api";
+import {
+  expireSignIn,
+  getAccessToken,
+  refreshAccessToken,
+  signOut,
+} from "./auth";
+import { syncOrigin } from "./config";
+import { SyncEngine, type FirstChoice, type SyncDevice } from "./engine";
+import { SYNCED_PREFS, type SyncedPref } from "./records";
+import {
+  getSyncAuth,
+  getSyncSettings,
+  getSyncState,
+  isSignedIn,
+  setSyncState,
+} from "./state";
+
+/**
+ * Sync for this extension: the engine over this device's storage, and the
+ * messages extension pages use to drive it in the background.
+ */
+
+const device: SyncDevice = {
+  profiles: listProfiles,
+  updateProfiles,
+  async prefs() {
+    const values = await Promise.all(SYNCED_PREFS.map((key) => Host.get(key)));
+    const prefs: Partial<Record<SyncedPref, unknown>> = {};
+    SYNCED_PREFS.forEach((key, i) => {
+      if (values[i] !== undefined) prefs[key] = values[i];
+    });
+    return prefs;
+  },
+  setPref: (key, value) => Host.set(key, value),
+  state: getSyncState,
+  setState: setSyncState,
+  settings: getSyncSettings,
+  signedIn: async () => isSignedIn(await getSyncAuth()),
+};
+
+// what this extension build runs on; it doesn't change while it runs
+let info: ReturnType<typeof Host.extensionInfo> | undefined;
+const extensionInfo = () => (info ??= Host.extensionInfo());
+
+async function api(deviceID: string): Promise<SyncApi> {
+  // the token the client last used, so a refresh after a 401 replaces that
+  // one and not one another context refreshed meanwhile
+  let used: string | undefined;
+  return new SyncApi({
+    origin: await syncOrigin(),
+    deviceID,
+    version: (await extensionInfo()).version,
+    getAccessToken: async () => (used = await getAccessToken()),
+    refreshAccessToken: async () => (used = await refreshAccessToken(used)),
+  });
+}
+
+let engine: Promise<SyncEngine> | undefined;
+
+/** The engine of this context; only the background runs it. */
+export function syncEngine(): Promise<SyncEngine> {
+  engine ??= extensionInfo().then(
+    (info) =>
+      new SyncEngine({
+        device,
+        api,
+        info,
+        onAuthRejected: expireSignIn,
+        onDeviceRevoked: signOut,
+      })
+  );
+  return engine;
+}
+
+// --- messages from extension pages ---
+
+export type SyncMessage =
+  | { type: "sync:run" }
+  | { type: "sync:first-choice"; choice: FirstChoice }
+  | { type: "sync:snapshots" }
+  | { type: "sync:restore"; snapshotID: string };
+
+type SyncReply<T = undefined> =
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+const isSyncMessage = (m: unknown): m is SyncMessage =>
+  typeof m === "object" &&
+  m !== null &&
+  typeof (m as { type?: unknown }).type === "string" &&
+  (m as { type: string }).type.startsWith("sync:");
+
+async function send<T>(message: SyncMessage): Promise<T> {
+  const reply: SyncReply<T> | undefined = await Host.sendMessage(message);
+  if (!reply) throw Error("The background didn't answer");
+  if (!reply.ok) throw Error(reply.error);
+  return reply.value;
+}
+
+/** Sync now; resolves when the run is done (its result is in the state). */
+export const requestSync = () => send<undefined>({ type: "sync:run" });
+
+/** Finish the first sync the way the user chose (spec §5.7). */
+export const chooseFirstSync = (choice: FirstChoice) =>
+  send<undefined>({ type: "sync:first-choice", choice });
+
+export const listSnapshots = () =>
+  send<SnapshotMeta[]>({ type: "sync:snapshots" });
+
+/** Restore the account to a snapshot, then sync it to this device. */
+export const restoreSnapshot = (snapshotID: string) =>
+  send<undefined>({ type: "sync:restore", snapshotID });
+
+async function handle(message: SyncMessage): Promise<unknown> {
+  const engine = await syncEngine();
+  switch (message.type) {
+    case "sync:run":
+      return engine.run({ trigger: "manual" });
+    case "sync:first-choice":
+      return engine.run({ trigger: "manual", firstChoice: message.choice });
+    case "sync:snapshots":
+      return (await withApi()).listSnapshots();
+    case "sync:restore":
+      await (await withApi()).restoreSnapshot(message.snapshotID);
+      return engine.run({ trigger: "manual" });
+  }
+}
+
+async function withApi(): Promise<SyncApi> {
+  const state = await getSyncState();
+  if (!state) throw Error("Not synced yet");
+  return api(state.deviceID);
+}
+
+/** Answer sync messages; call once, in the background. */
+export function handleSyncMessages() {
+  Host.onMessage((message, _sender, sendResponse) => {
+    if (!isSyncMessage(message)) return;
+    handle(message).then(
+      (value) => sendResponse({ ok: true, value: value ?? undefined }),
+      (e) => sendResponse({ ok: false, error: String(e?.message ?? e) })
+    );
+    return true; // Chrome: the response comes asynchronously
+  });
+}
diff --git a/src/services/sync/records.ts b/src/services/sync/records.ts
new file mode 100644
index 0000000..9fc5d2c
--- /dev/null
+++ b/src/services/sync/records.ts
@@ -0,0 +1,262 @@
+import * as inner from "@/services/profile";
+import { exportableProfile } from "@/services/config/proxyverse";
+import {
+  FORMAT_VERSION,
+  ProxyProfile,
+} from "@/services/config/proxyverse/schema";
+import { DarkMode, defaultDarkMode, keyDarkMode } from "@/services/theme";
+import { defaultLanguage, keyLanguage } from "@/services/i18n";
+import { defaultActionBehavior, keyActionBehavior } from "@/services/ui";
+import { deepClone } from "@/services/utils";
+
+/**
+ * The records of sync (spec §3): what local storage turns into on the wire,
+ * and back. One profile or one preference is one record.
+ */
+
+/** Payload schema version: the config file format (spec §3.5). */
+export const PAYLOAD_SCHEMA = FORMAT_VERSION;
+/** The only payload encoding v1 reads and writes (spec §3.4). */
+export const PAYLOAD_ENCODING = "json";
+
+/** The preferences that sync. New ones are added here explicitly. */
+export const SYNCED_PREFS = [
+  keyDarkMode,
+  keyLanguage,
+  keyActionBehavior,
+] as const;
+export type SyncedPref = (typeof SYNCED_PREFS)[number];
+
+/** Each synced pref's value when unset, from the module that owns it. */
+export const SYNCED_PREF_DEFAULTS: Record<SyncedPref, unknown> = {
+  [keyDarkMode]: defaultDarkMode,
+  [keyLanguage]: defaultLanguage,
+  [keyActionBehavior]: defaultActionBehavior,
+};
+
+export type ProfilePayload = ProxyProfile;
+export type PrefPayload = { value: number | string };
+export type Payload = ProfilePayload | PrefPayload;
+
+const PROFILE_PREFIX = "profile:";
+const PREF_PREFIX = "pref:";
+
+export const profileRecordID = (profileID: string) =>
+  `${PROFILE_PREFIX}${profileID}`;
+export const prefRecordID = (key: SyncedPref) => `${PREF_PREFIX}${key}`;
+
+export type ParsedRecordID =
+  | { kind: "profile"; profileID: string }
+  | { kind: "pref"; key: SyncedPref };
+
+/** What a record ID names; undefined for unknown kinds or prefs. */
+export function parseRecordID(id: string): ParsedRecordID | undefined {
+  if (id.startsWith(PROFILE_PREFIX)) {
+    const profileID = id.slice(PROFILE_PREFIX.length);
+    return profileID ? { kind: "profile", profileID } : undefined;
+  }
+  if (id.startsWith(PREF_PREFIX)) {
+    const key = id.slice(PREF_PREFIX.length);
+    return isSyncedPref(key) ? { kind: "pref", key } : undefined;
+  }
+  return undefined;
+}
+
+const isSyncedPref = (key: string): key is SyncedPref =>
+  (SYNCED_PREFS as readonly string[]).includes(key);
+
+// --- preferences ---
+
+// a numeric enum's values also hold its member names
+const DARK_MODES: unknown[] = Object.values(DarkMode).filter(
+  (v) => typeof v === "number"
+);
+// lenient, as on the server: a new locale needs no schema bump
+const LANGUAGE_CODE = /^[a-z]{2,3}(_[A-Z]{2})?$/;
+
+/** Whether `value` is valid for pref `key`, by the server's rules (§3.2). */
+export function isValidPrefValue(key: SyncedPref, value: unknown): boolean {
+  switch (key) {
+    case keyDarkMode:
+      return DARK_MODES.includes(value);
+    case keyLanguage:
+      return (
+        value === "auto" ||
+        (typeof value === "string" && LANGUAGE_CODE.test(value))
+      );
+    case keyActionBehavior:
+      return value === "popup" || value === "sidebar";
+  }
+}
+
+function decodePref(key: SyncedPref, data: unknown): PrefPayload | undefined {
+  if (typeof data !== "object" || data === null || !("value" in data)) {
+    return undefined;
+  }
+  const { value } = data;
+  return isValidPrefValue(key, value)
+    ? { value: value as PrefPayload["value"] }
+    : undefined;
+}
+
+// --- profiles ---
+
+/**
+ * A profile as it syncs (spec §3.6): the export format, which drops runtime
+ * fields (e.g. `pacScript.lastFetched`), without the fetched script of a
+ * PAC URL (each device fetches it) and with the color upper-cased, as the
+ * profile editor saves it. Undefined for system or invalid profiles.
+ */
+export function normalizeProfile(
+  p: inner.ProxyProfile
+): ProfilePayload | undefined {
+  // a copy: zod keeps nested arrays' items by reference, and `p` may be
+  // a Vue proxy
+  const payload = exportableProfile(deepClone(p));
+  if (!payload) return undefined;
+
+  payload.color = payload.color.toUpperCase();
+  if (payload.proxyType === "pac" && payload.pacScript.sourceURL) {
+    delete payload.pacScript.data;
+  }
+  return payload;
+}
+
+/**
+ * A remote record's payload, normalized: undefined if this version can't
+ * read it (an invalid payload, an unknown pref, a system profile, or a
+ * profile not matching its record ID).
+ */
+export function decodeRemote(id: string, data: unknown): Payload | undefined {
+  const parsed = parseRecordID(id);
+  if (parsed?.kind === "pref") return decodePref(parsed.key, data);
+  if (parsed?.kind === "profile") return decodeProfile(parsed.profileID, data);
+  return undefined;
+}
+
+function decodeProfile(profileID: string, data: unknown): ProfilePayload | undefined {
+  if (inner.getSystemProfile(profileID)) return undefined;
+
+  const profile = ProxyProfile.safeParse(data);
+  if (!profile.success || profile.data.profileID !== profileID) {
+    return undefined;
+  }
+  // normalized, so its hash matches the one this device computes once the
+  // profile is stored
+  return normalizeProfile(profile.data);
+}
+
+/**
+ * The profile to store for a remote payload. A PAC URL profile whose URL
+ * didn't change keeps this device's fetched script and fetch status;
+ * otherwise it's stored without a script, so the PAC fetcher fetches it.
+ */
+export function mergeIncomingProfile(
+  remote: ProfilePayload,
+  localExisting?: inner.ProxyProfile
+): inner.ProxyProfile {
+  const merged: inner.ProxyProfile = deepClone(remote);
+  const sourceURL =
+    merged.proxyType === "pac" ? merged.pacScript.sourceURL : undefined;
+  if (
+    merged.proxyType !== "pac" ||
+    !sourceURL ||
+    localExisting?.proxyType !== "pac" ||
+    localExisting.pacScript.sourceURL !== sourceURL
+  ) {
+    return merged;
+  }
+
+  const { data, lastFetched, lastError } = localExisting.pacScript;
+  merged.pacScript = deepClone({
+    ...merged.pacScript,
+    data,
+    lastFetched,
+    lastError,
+  });
+  return merged;
+}
+
+// --- hashing ---
+
+/**
+ * JSON with object keys sorted and no whitespace, so equal payloads always
+ * serialize, and hash, the same. Like `JSON.stringify`, it drops undefined
+ * object members and writes undefined array items as null.
+ */
+export function canonicalJSON(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value
+      .map((v) => (v === undefined ? "null" : canonicalJSON(v)))
+      .join(",")}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    const obj = value as Record<string, unknown>;
+    const members = Object.keys(obj)
+      .sort()
+      .filter((k) => obj[k] !== undefined)
+      .map((k) => `${JSON.stringify(k)}:${canonicalJSON(obj[k])}`);
+    return `{${members.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+/** SHA-256 (hex) of a payload's canonical JSON (spec §3.6). */
+export async function hashPayload(payload: unknown): Promise<string> {
+  const bytes = new TextEncoder().encode(canonicalJSON(payload));
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest), (b) =>
+    b.toString(16).padStart(2, "0")
+  ).join("");
+}
+
+// --- local state ---
+
+export type LocalRecord = { payload: Payload; hash: string };
+
+export type LocalSource = {
+  profiles: inner.ProfilesStorage;
+  /** Stored values of the synced prefs; unset ones are absent. */
+  prefs: Partial<Record<SyncedPref, unknown>>;
+  /** Profile IDs that stay on this device (spec §5.6). */
+  localOnly: string[];
+  syncPrefs: boolean;
+};
+
+/**
+ * The records this device's storage holds, by record ID. System profiles,
+ * local-only and invalid profiles are left out, as are prefs that are unset,
+ * invalid, or not synced on this device.
+ */
+export async function collectLocalRecords({
+  profiles,
+  prefs,
+  localOnly,
+  syncPrefs,
+}: LocalSource): Promise<Map<string, LocalRecord>> {
+  const payloads: [string, Payload][] = [];
+  const skipped = new Set(localOnly);
+
+  for (const [key, profile] of Object.entries(profiles)) {
+    if (skipped.has(key) || inner.getSystemProfile(key)) continue;
+    const payload = normalizeProfile(profile);
+    // another device rejects a payload naming a different profile
+    if (!payload || payload.profileID !== key) continue;
+    payloads.push([profileRecordID(key), payload]);
+  }
+
+  if (syncPrefs) {
+    for (const key of SYNCED_PREFS) {
+      const value = prefs[key];
+      if (value === undefined || !isValidPrefValue(key, value)) continue;
+      payloads.push([prefRecordID(key), { value: value as PrefPayload["value"] }]);
+    }
+  }
+
+  const hashes = await Promise.all(payloads.map(([, p]) => hashPayload(p)));
+  const records = new Map<string, LocalRecord>(
+    payloads.map(([id, payload], i) => [id, { payload, hash: hashes[i] }])
+  );
+
+  return records;
+}
diff --git a/src/services/sync/state.ts b/src/services/sync/state.ts
new file mode 100644
index 0000000..0c1d015
--- /dev/null
+++ b/src/services/sync/state.ts
@@ -0,0 +1,155 @@
+import { Host } from "@/adapters";
+import { deepClone, withLock } from "@/services/utils";
+import type { SyncRecord } from "./api";
+
+/**
+ * Sync's own storage (spec §5.1), in `storage.local` and never synced:
+ * the tokens, the engine's bookkeeping, and this device's sync settings.
+ */
+
+export const keySyncAuth = "sync.auth";
+export const keySyncState = "sync.state";
+export const keySyncSettings = "sync.settings";
+const SYNC_KEYS = [keySyncAuth, keySyncState, keySyncSettings] as const;
+type SyncStorageKey = (typeof SYNC_KEYS)[number];
+
+export type SyncAuth = {
+  accessToken: string;
+  refreshToken: string;
+  /** When the access token expires, in ms since the epoch. */
+  expiresAt: number;
+  /** From userinfo: `sub` tells a different account apart, `email` is shown. */
+  account?: { sub?: string; email?: string };
+  /** The refresh token was refused: signed out until the user signs in. */
+  expired?: boolean;
+};
+
+export type SyncState = {
+  deviceID: string;
+  /** The highest server `rev` applied. */
+  cursor: number;
+  /** The last HLC issued or seen. */
+  clock?: string;
+  /** The last version agreed with the server, per record. */
+  base: Record<string, { rev: number; hlc: string; hash: string }>;
+  /** This device's current version, per record. */
+  local: Record<string, { hlc: string; hash: string }>;
+  /** Records with a schema or encoding this version can't read (§3.5). */
+  held: Record<string, SyncRecord>;
+  /**
+   * The first sync found data on both this device and the account, and
+   * waits for the user to choose how to combine them (spec §5.7).
+   */
+  needsFirstChoice?: boolean;
+  lastSync?: { at: number; error?: { code: string; message?: string } };
+  /** The first sync with the account is done (spec §5.7). */
+  synced?: boolean;
+  /**
+   * Records the server refused for good (e.g. too large): not pushed again
+   * until they change locally, so a bad record doesn't fail every run.
+   */
+  failed?: Record<string, { reason: string; hash: string }>;
+  /** Don't sync on its own before `until` (ms), after `attempts` failures. */
+  backoff?: { until: number; attempts: number };
+  /** The extension version this device last registered with. */
+  registered?: string;
+};
+
+export type SyncSettings = {
+  /** Whether `pref:*` records sync on this device, both ways. */
+  syncPrefs: boolean;
+  /** Profile IDs that stay on this device (spec §5.6). */
+  localOnly: string[];
+};
+
+export const DEFAULT_SYNC_SETTINGS: SyncSettings = {
+  syncPrefs: true,
+  localOnly: [],
+};
+
+/** The state of a device that has never synced. */
+export const initialSyncState = (): SyncState => ({
+  deviceID: globalThis.crypto.randomUUID(),
+  cursor: 0,
+  base: {},
+  local: {},
+  held: {},
+});
+
+/** Signed in, with a sign-in the server hasn't refused. */
+export const isSignedIn = (auth: SyncAuth | undefined): auth is SyncAuth =>
+  !!auth && !auth.expired;
+
+// --- auth ---
+
+export async function getSyncAuth(): Promise<SyncAuth | undefined> {
+  return Host.get<SyncAuth>(keySyncAuth);
+}
+
+export async function setSyncAuth(auth: SyncAuth) {
+  await Host.set(keySyncAuth, deepClone(auth));
+}
+
+export async function clearSyncAuth() {
+  await Host.remove(keySyncAuth);
+}
+
+// --- state ---
+
+export async function getSyncState(): Promise<SyncState | undefined> {
+  return Host.get<SyncState>(keySyncState);
+}
+
+export async function setSyncState(state: SyncState) {
+  await Host.set(keySyncState, deepClone(state));
+}
+
+export async function clearSyncState() {
+  await Host.remove(keySyncState);
+}
+
+// --- settings ---
+
+/** Stored settings with missing fields filled in with their defaults. */
+export const withSyncDefaults = (
+  stored: Partial<SyncSettings> | undefined
+): SyncSettings => ({ ...DEFAULT_SYNC_SETTINGS, ...stored });
+
+/** This device's settings; missing fields get their defaults. */
+export async function getSyncSettings(): Promise<SyncSettings> {
+  return withSyncDefaults(await Host.get<Partial<SyncSettings>>(keySyncSettings));
+}
+
+/**
+ * Change this device's settings. Read-modify-write under a lock shared by
+ * every extension context, so two pages changing different settings don't
+ * overwrite each other.
+ */
+export function updateSyncSettings(
+  mutate: (settings: SyncSettings) => void
+): Promise<void> {
+  return withLock("proxyverse-sync-settings", async () => {
+    const settings = await getSyncSettings();
+    mutate(settings);
+    await Host.set(keySyncSettings, deepClone(settings));
+  });
+}
+
+/**
+ * Subscribe to writes of the sync keys, from any extension context. The
+ * callback gets the changes of those keys only. Returns an unsubscribe.
+ */
+export function onSyncStorageChanged(
+  callback: (
+    changes: Partial<
+      Record<SyncStorageKey, { newValue?: unknown; oldValue?: unknown }>
+    >
+  ) => void
+): () => void {
+  return Host.onLocalStorageChanged((changes) => {
+    const ours = Object.fromEntries(
+      SYNC_KEYS.filter((k) => k in changes).map((k) => [k, changes[k]])
+    );
+    if (Object.keys(ours).length) callback(ours);
+  });
+}
diff --git a/src/services/theme.ts b/src/services/theme.ts
new file mode 100644
index 0000000..26d9b01
--- /dev/null
+++ b/src/services/theme.ts
@@ -0,0 +1,13 @@
+// The theme setting's storage key and values, without Vue, so the background
+// (which syncs the setting) doesn't bundle Vue. `preference.ts` applies it.
+
+export const keyDarkMode = "theme.darkmode";
+
+export enum DarkMode {
+  Default = 0,
+  Dark = 1,
+  Light = 2,
+}
+
+/** Unset means following the system theme. */
+export const defaultDarkMode = DarkMode.Default;
diff --git a/src/services/ui.ts b/src/services/ui.ts
index 12c282e..a262472 100644
--- a/src/services/ui.ts
+++ b/src/services/ui.ts
@@ -3,11 +3,12 @@ import type { ActionBehavior } from "@/adapters/base";
 
 export type { ActionBehavior } from "@/adapters/base";
 
-const keyActionBehavior = "ui.actionBehavior";
+export const keyActionBehavior = "ui.actionBehavior";
+export const defaultActionBehavior: ActionBehavior = "popup";
 
 /** What a click on the toolbar icon opens: the popup unless chosen otherwise. */
 export async function getActionBehavior(): Promise<ActionBehavior> {
-  return Host.getWithDefault<ActionBehavior>(keyActionBehavior, "popup");
+  return Host.getWithDefault<ActionBehavior>(keyActionBehavior, defaultActionBehavior);
 }
 
 export async function setActionBehavior(behavior: ActionBehavior) {
@@ -20,7 +21,9 @@ export function onActionBehaviorChanged(
 ): () => void {
   return Host.onLocalStorageChanged((changes) => {
     if (keyActionBehavior in changes) {
-      callback((changes[keyActionBehavior].newValue as ActionBehavior) ?? "popup");
+      callback(
+        (changes[keyActionBehavior].newValue as ActionBehavior) ?? defaultActionBehavior
+      );
     }
   });
 }
diff --git a/src/services/utils.ts b/src/services/utils.ts
index 6ae98aa..da981fa 100644
--- a/src/services/utils.ts
+++ b/src/services/utils.ts
@@ -34,3 +34,23 @@ export function decodeBase64(text: string): string {
     Uint8Array.from(binary, (c) => c.charCodeAt(0))
   );
 }
+
+const fallbackLocks = new Map<string, Promise<unknown>>();
+
+/**
+ * Run `fn` holding the named lock, so read-modify-write sequences on storage
+ * don't interleave. Web Locks span every extension context (pages and the
+ * background); where they're missing, fall back to a lock local to this context.
+ */
+export function withLock<T>(name: string, fn: () => Promise<T>): Promise<T> {
+  const locks = globalThis.navigator?.locks;
+  if (locks) return locks.request(name, fn);
+
+  const prev = fallbackLocks.get(name) ?? Promise.resolve();
+  const run = prev.then(fn, fn);
+  fallbackLocks.set(
+    name,
+    run.catch(() => undefined)
+  );
+  return run;
+}
diff --git a/tests/build/manifest.test.ts b/tests/build/manifest.test.ts
new file mode 100644
index 0000000..893bdcc
--- /dev/null
+++ b/tests/build/manifest.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, test } from "vitest";
+import base from "../../manifest.json";
+import { buildManifest, crxVersion } from "../../build/manifest.ts";
+import { BUILD_ENVS, parseBuildEnv, syncDefines } from "../../build/env.ts";
+
+const KEY = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAdevkey";
+const common = { version: "1.2.3-beta", serviceWorker: "assets/bg-abc.js" };
+
+// the Chrome production manifest: the root one with the version and the
+// built service worker filled in
+const chromeExpected = () => {
+  const m: any = JSON.parse(JSON.stringify(base));
+  m.version = "1.2.3";
+  m.version_name = "1.2.3-beta";
+  m.background.service_worker = "assets/bg-abc.js";
+  return m;
+};
+
+describe("buildManifest", () => {
+  test("Chrome production fills in the version and service worker only", () => {
+    const m: any = buildManifest(base, { ...common, mode: "chrome", env: "production" });
+    expect(m).toEqual(chromeExpected());
+    // sync's sign-in window; no install or update warning on Chrome
+    expect(m.permissions).toContain("identity");
+    expect(m).not.toHaveProperty("optional_permissions");
+    expect(m).not.toHaveProperty("key");
+  });
+
+  test("does not mutate its input", () => {
+    const copy = JSON.parse(JSON.stringify(base));
+    buildManifest(base, { ...common, mode: "firefox", env: "e2e" });
+    buildManifest(base, { ...common, mode: "chrome", env: "e2e", devKey: KEY });
+    expect(base).toEqual(copy);
+  });
+
+  test("Firefox: gecko and sidebar transforms", () => {
+    const m: any = buildManifest(base, { ...common, mode: "firefox", env: "production" });
+    expect(m.permissions).toContain("identity");
+    expect(m.permissions).not.toContain("sidePanel");
+    expect(m).not.toHaveProperty("optional_permissions");
+    expect(m.background).toEqual({ type: "module", scripts: ["assets/bg-abc.js"] });
+    expect(m).not.toHaveProperty("version_name");
+    expect(m.version).toBe("1.2.3");
+    expect(m).not.toHaveProperty("side_panel");
+    expect(m.sidebar_action).toEqual({
+      default_panel: "index.html#/sidebar",
+      default_icon: "mini-logo.png",
+      open_at_install: false,
+    });
+    expect(m.browser_specific_settings).toEqual({
+      gecko: { id: "proxyverse@byte.vet", strict_min_version: "115.0" },
+    });
+    expect(m).not.toHaveProperty("key");
+  });
+
+  test("Chrome dev builds carry the key, production never does", () => {
+    for (const env of ["northernlight", "e2e"] as const) {
+      const m = buildManifest(base, { ...common, mode: "chrome", env, devKey: KEY });
+      expect(m.key).toBe(KEY);
+    }
+    for (const mode of ["chrome", "firefox"] as const) {
+      const m = buildManifest(
+        { ...base, key: "stale" },
+        { ...common, mode, env: "production", devKey: KEY }
+      );
+      expect(m).not.toHaveProperty("key");
+    }
+    expect(
+      buildManifest(base, { ...common, mode: "firefox", env: "northernlight", devKey: KEY })
+    ).not.toHaveProperty("key");
+  });
+
+  test("a Chrome dev build without the key fails", () => {
+    expect(() =>
+      buildManifest(base, { ...common, mode: "chrome", env: "northernlight" })
+    ).toThrow(/dev key/);
+  });
+});
+
+describe("crxVersion", () => {
+  test("from CRX_VER", () => {
+    expect(crxVersion(undefined)).toBe("0.0.0-dev");
+    expect(crxVersion("v1.2.3")).toBe("1.2.3");
+    expect(crxVersion("1.2.3-rc.1234567890")).toBe("1.2.3-rc.12345");
+  });
+});
+
+describe("build env", () => {
+  test("parses PROXYVERSE_ENV", () => {
+    expect(parseBuildEnv(undefined)).toBe("production");
+    expect(parseBuildEnv("")).toBe("production");
+    expect(parseBuildEnv("northernlight")).toBe("northernlight");
+    expect(parseBuildEnv("e2e")).toBe("e2e");
+    expect(() => parseBuildEnv("staging")).toThrow(/Unknown PROXYVERSE_ENV "staging"/);
+    expect(() => parseBuildEnv("toString")).toThrow();
+  });
+
+  test("defines JSON literals", () => {
+    expect(syncDefines("production")).toEqual({
+      __SYNC_ORIGIN__: '"https://byte.vet"',
+      __SYNC_CLIENT_ID__: '"proxyverse-extension"',
+      __SYNC_ORIGIN_OVERRIDE__: "false",
+    });
+    expect(BUILD_ENVS.northernlight.clientID).toBe("proxyverse-extension-dev");
+    expect(syncDefines("e2e").__SYNC_ORIGIN_OVERRIDE__).toBe("true");
+  });
+});
diff --git a/tests/components/relativeTime.test.ts b/tests/components/relativeTime.test.ts
new file mode 100644
index 0000000..ebdf077
--- /dev/null
+++ b/tests/components/relativeTime.test.ts
@@ -0,0 +1,22 @@
+import { expect, test } from "vitest";
+import { relativeTime } from "@/components/sync/relativeTime";
+
+const NOW = Date.UTC(2026, 9, 27, 12);
+const ago = (seconds: number) =>
+  relativeTime(NOW - seconds * 1000, NOW, "en", "a few seconds ago");
+
+test("reads as how long ago, in the largest fitting unit", () => {
+  expect(ago(5)).toBe("a few seconds ago");
+  expect(ago(59)).toBe("a few seconds ago");
+  expect(ago(60)).toBe("1 minute ago");
+  expect(ago(90)).toBe("1 minute ago");
+  expect(ago(59 * 60)).toBe("59 minutes ago");
+  expect(ago(3 * 3600)).toBe("3 hours ago");
+  expect(ago(26 * 3600)).toBe("yesterday");
+  expect(ago(3 * 86400)).toBe("3 days ago");
+  expect(ago(20 * 86400)).toBe("2 weeks ago");
+});
+
+test("follows the UI language", () => {
+  expect(relativeTime(NOW - 5 * 60_000, NOW, "zh-CN", "")).toBe("5分钟前");
+});
diff --git a/tests/helpers.ts b/tests/helpers.ts
new file mode 100644
index 0000000..7935215
--- /dev/null
+++ b/tests/helpers.ts
@@ -0,0 +1,39 @@
+// Fixtures shared by unit tests.
+import { vi } from "vitest";
+import { Host } from "@/adapters";
+import type { ProxyProfile } from "@/services/profile";
+
+/** A valid proxy profile (it passes the export schema). */
+export const proxyProfile = (profileID: string, host = "10.0.0.1"): ProxyProfile => ({
+  profileID,
+  color: "#AABBCC",
+  profileName: profileID,
+  proxyType: "proxy",
+  proxyRules: { default: { scheme: "http", host, port: 8080 }, bypassList: [] },
+});
+
+/** A JSON `Response`. */
+export const jsonResponse = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+
+/**
+ * Back `Host`'s local storage with a plain object, returned for inspection.
+ * Values are copied in and out, as browser storage does. Restore with
+ * `vi.restoreAllMocks()`.
+ */
+export function fakeLocalStorage(initial: Record<string, unknown> = {}) {
+  const store: Record<string, unknown> = { ...initial };
+  vi.spyOn(Host, "get").mockImplementation(async (key: string) =>
+    structuredClone(store[key]) as never
+  );
+  vi.spyOn(Host, "set").mockImplementation(async (key, value) => {
+    store[key] = structuredClone(value);
+  });
+  vi.spyOn(Host, "remove").mockImplementation(async (key) => {
+    delete store[key];
+  });
+  return store;
+}
diff --git a/tests/services/profileLock.test.ts b/tests/services/profileLock.test.ts
new file mode 100644
index 0000000..2dfda0a
--- /dev/null
+++ b/tests/services/profileLock.test.ts
@@ -0,0 +1,29 @@
+import { afterEach, expect, test, vi } from "vitest";
+import { Host } from "@/adapters";
+import { deleteProfile, listProfiles, saveProfile } from "@/services/profile";
+import { proxyProfile as proxy } from "../helpers";
+
+afterEach(() => vi.restoreAllMocks());
+
+test("concurrent profile writes don't lose each other's changes", async () => {
+  let stored: unknown = { gone: proxy("gone") };
+  // A slow storage widens the read-modify-write window.
+  const tick = () => new Promise((r) => setTimeout(r, 5));
+  vi.spyOn(Host, "get").mockImplementation(async () => {
+    await tick();
+    return structuredClone(stored);
+  });
+  vi.spyOn(Host, "set").mockImplementation(async (_, val) => {
+    await tick();
+    stored = val;
+  });
+
+  await Promise.all([
+    saveProfile(proxy("a")),
+    saveProfile(proxy("b")),
+    deleteProfile("gone"),
+    saveProfile(proxy("c")),
+  ]);
+
+  expect(Object.keys(await listProfiles()).sort()).toEqual(["a", "b", "c"]);
+});
diff --git a/tests/services/proxy/refreshProxy.test.ts b/tests/services/proxy/refreshProxy.test.ts
new file mode 100644
index 0000000..ff04259
--- /dev/null
+++ b/tests/services/proxy/refreshProxy.test.ts
@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { Host } from "@/adapters";
+import type { ProfilesStorage, ProxyProfile } from "@/services/profile";
+import { refreshProxyOnProfileUpdate } from "@/services/proxy";
+import { fakeLocalStorage, proxyProfile as proxy } from "../../helpers";
+
+// A fake browser where this extension controls the proxy and `active` is the
+// stored active-profile snapshot.
+function mockBrowser(active: ProxyProfile, profiles: ProfilesStorage) {
+  const store = fakeLocalStorage({ "active-profile": active, profiles });
+  vi.spyOn(Host, "getProxySettings").mockResolvedValue({
+    levelOfControl: "controlled_by_this_extension",
+    value: { mode: "fixed_servers" },
+  } as any);
+  const setProxy = vi.spyOn(Host, "setProxy").mockResolvedValue();
+  vi.spyOn(Host, "clearProxy").mockResolvedValue();
+  return { store, setProxy };
+}
+
+describe("refreshProxyOnProfileUpdate", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  test("falls back to direct when the active profile is deleted", async () => {
+    const old = { a: proxy("a") };
+    const { store, setProxy } = mockBrowser(proxy("a"), {});
+
+    await refreshProxyOnProfileUpdate({}, old);
+
+    expect((store["active-profile"] as ProxyProfile).profileID).toBe("direct");
+    expect(setProxy).toHaveBeenCalledWith(
+      expect.objectContaining({ mode: "direct" })
+    );
+  });
+
+  test("re-applies the active profile when it changes", async () => {
+    const changed = { ...proxy("a"), profileName: "renamed" };
+    const { store } = mockBrowser(proxy("a"), { a: changed });
+
+    await refreshProxyOnProfileUpdate({ a: changed }, { a: proxy("a") });
+
+    expect(store["active-profile"]).toEqual(changed);
+  });
+
+  test("ignores changes to profiles the active one doesn't use", async () => {
+    const { setProxy } = mockBrowser(proxy("a"), { a: proxy("a") });
+
+    await refreshProxyOnProfileUpdate(
+      { a: proxy("a"), b: proxy("b") },
+      { a: proxy("a") }
+    );
+
+    expect(setProxy).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/services/sync/api-gen.test.ts b/tests/services/sync/api-gen.test.ts
new file mode 100644
index 0000000..a7fb1df
--- /dev/null
+++ b/tests/services/sync/api-gen.test.ts
@@ -0,0 +1,16 @@
+import { expect, test } from "vitest";
+import spec from "@/../docs/sync-api.openapi.yaml?raw";
+import generated from "@/services/sync/api.gen.ts?raw";
+
+// api.gen.ts is stamped with the SHA-256 of the contract it came from
+// (scripts/sync-api-types.mjs); a contract update without regenerating
+// fails here.
+test("api.gen.ts matches the vendored OpenAPI contract", async () => {
+  const stamped = /^\/\/ openapi-sha256: ([0-9a-f]{64})$/m.exec(generated)?.[1];
+  const bytes = new TextEncoder().encode(spec);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  const actual = Array.from(new Uint8Array(digest), (b) =>
+    b.toString(16).padStart(2, "0")
+  ).join("");
+  expect(stamped === actual, "regenerate: npm run sync:api-types").toBe(true);
+});
diff --git a/tests/services/sync/api.test.ts b/tests/services/sync/api.test.ts
new file mode 100644
index 0000000..b2ac583
--- /dev/null
+++ b/tests/services/sync/api.test.ts
@@ -0,0 +1,197 @@
+import { describe, expect, test, vi } from "vitest";
+import { SyncApi, SyncApiError } from "@/services/sync/api";
+import { jsonResponse } from "../../helpers";
+
+const ORIGIN = "https://sync.example";
+const DEVICE = "7b1e0000-0000-4000-8000-000000000001";
+
+type Call = {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: unknown;
+};
+
+/** A fake fetch answering from a queue, recording each call. */
+function fakeFetch(...responses: (Response | Error)[]) {
+  const calls: Call[] = [];
+  const fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({
+      url: String(input),
+      method: init?.method ?? "GET",
+      headers: init?.headers as Record<string, string>,
+      body: init?.body === undefined ? undefined : JSON.parse(String(init.body)),
+    });
+    const next = responses.shift();
+    if (!next) throw Error("unexpected request");
+    if (next instanceof Error) throw next;
+    return next;
+  });
+  return { fetch: fetch as unknown as typeof globalThis.fetch, calls };
+}
+
+const json = jsonResponse;
+
+const problem = (status: number, code: string, headers: Record<string, string> = {}) =>
+  new Response(
+    JSON.stringify({ type: "about:blank", title: code, status, code, detail: `${code} happened` }),
+    { status, headers: { "Content-Type": "application/problem+json", ...headers } }
+  );
+
+function client(f: ReturnType<typeof fakeFetch>, tokens = ["t1", "t2"]) {
+  const refresh = vi.fn(async () => tokens[1]);
+  const api = new SyncApi({
+    origin: ORIGIN,
+    deviceID: DEVICE,
+    version: "2.3.0",
+    getAccessToken: async () => tokens[0],
+    refreshAccessToken: refresh,
+    fetch: f.fetch,
+  });
+  return { api, refresh };
+}
+
+const record = {
+  id: "pref:ui.language",
+  rev: 3,
+  hlc: `001730023456789:0000:${DEVICE}`,
+  deviceID: DEVICE,
+  deleted: false,
+  schema: "2025-01",
+  encoding: "json",
+  data: { value: "en" },
+};
+
+describe("SyncApi requests", () => {
+  test("sends auth, device and version headers", async () => {
+    const f = fakeFetch(json({ records: [record], cursor: 3, hasMore: false }));
+    const { api } = client(f);
+    expect(await api.changes(0)).toEqual({ records: [record], cursor: 3, hasMore: false });
+    expect(f.calls[0]).toEqual({
+      url: `${ORIGIN}/api/proxyverse/v1/changes?since=0`,
+      method: "GET",
+      headers: {
+        Authorization: "Bearer t1",
+        "X-Proxyverse-Device": DEVICE,
+        "X-Proxyverse-Version": "2.3.0",
+      },
+      body: undefined,
+    });
+  });
+
+  test("maps each method to its endpoint", async () => {
+    const meta = { id: "s1", createdAt: 1, reason: "manual", rev: 3, recordCount: 1, createdBy: DEVICE };
+    const device = { id: DEVICE, name: "Chrome", browser: "chrome", extVersion: "2.3.0", createdAt: 1, lastSeen: 2 };
+    const f = fakeFetch(
+      json(device),
+      json({ records: [], cursor: 9, hasMore: false }),
+      json({ accepted: [{ id: record.id, rev: 4 }], rejected: [] }),
+      json([meta]),
+      json(meta, 201),
+      json(meta, 201),
+      json({ rev: 10, written: 1 })
+    );
+    const { api } = client(f);
+    const { rev: _, deviceID: __, ...push } = record;
+
+    await api.putDevice({ name: "Chrome" });
+    await api.changes(5);
+    expect(await api.push([push])).toEqual({ accepted: [{ id: record.id, rev: 4 }], rejected: [] });
+    expect(await api.listSnapshots()).toEqual([meta]);
+    await api.createSnapshot();
+    await api.createSnapshot("before-overwrite");
+    expect(await api.restoreSnapshot("s/1")).toEqual({ rev: 10, written: 1 });
+
+    const base = `${ORIGIN}/api/proxyverse/v1`;
+    expect(f.calls.map((c) => [c.method, c.url, c.body])).toEqual([
+      ["PUT", `${base}/devices/${DEVICE}`, { name: "Chrome" }],
+      ["GET", `${base}/changes?since=5`, undefined],
+      ["POST", `${base}/records`, { records: [push] }],
+      ["GET", `${base}/snapshots`, undefined],
+      ["POST", `${base}/snapshots`, undefined],
+      ["POST", `${base}/snapshots`, { reason: "before-overwrite" }],
+      ["POST", `${base}/snapshots/s%2F1/restore`, undefined],
+    ]);
+    expect(f.calls[0].headers["Content-Type"]).toBe("application/json");
+    expect(f.calls[1].headers).not.toHaveProperty("Content-Type");
+  });
+
+});
+
+describe("SyncApi errors", () => {
+  test("throws problem details with their code", async () => {
+    const { api } = client(fakeFetch(problem(410, "cursor_expired")));
+    const err = await api.changes(1).catch((e) => e);
+    expect(err).toBeInstanceOf(SyncApiError);
+    expect(err).toMatchObject({ status: 410, code: "cursor_expired", detail: "cursor_expired happened" });
+    expect(err.retryAfter).toBeUndefined();
+  });
+
+  test("exposes Retry-After in seconds, without retrying", async () => {
+    const f = fakeFetch(
+      problem(429, "rate_limited", { "Retry-After": "120" }),
+      problem(503, "unavailable", { "Retry-After": new Date(Date.now() + 30_000).toUTCString() })
+    );
+    const { api } = client(f);
+    await expect(api.changes(0)).rejects.toMatchObject({ status: 429, code: "rate_limited", retryAfter: 120 });
+    const err = await api.changes(0).catch((e) => e);
+    expect(err.code).toBe("unavailable");
+    expect(err.retryAfter).toBeGreaterThan(25);
+    expect(err.retryAfter).toBeLessThanOrEqual(30);
+    expect(f.calls).toHaveLength(2);
+  });
+
+  test("a network failure is code network, status 0", async () => {
+    const { api } = client(fakeFetch(new TypeError("Failed to fetch")));
+    await expect(api.listSnapshots()).rejects.toMatchObject({ status: 0, code: "network" });
+  });
+
+  test("an unreadable body is code invalid_response", async () => {
+    const f = fakeFetch(
+      new Response("<html>bad gateway</html>", { status: 502, headers: { "Content-Type": "text/html" } }),
+      new Response("not json", { status: 200, headers: { "Content-Type": "application/json" } })
+    );
+    const { api } = client(f);
+    await expect(api.changes(0)).rejects.toMatchObject({ status: 502, code: "invalid_response" });
+    await expect(api.changes(0)).rejects.toMatchObject({ status: 200, code: "invalid_response" });
+  });
+});
+
+describe("SyncApi token refresh", () => {
+  test("refreshes once on 401 invalid_token and retries", async () => {
+    const f = fakeFetch(problem(401, "invalid_token"), json([]));
+    const { api, refresh } = client(f);
+    expect(await api.listSnapshots()).toEqual([]);
+    expect(refresh).toHaveBeenCalledOnce();
+    expect(f.calls.map((c) => c.headers.Authorization)).toEqual(["Bearer t1", "Bearer t2"]);
+  });
+
+  test("gives up when the retry is refused too", async () => {
+    const f = fakeFetch(problem(401, "invalid_token"), problem(401, "invalid_token"));
+    const { api, refresh } = client(f);
+    await expect(api.listSnapshots()).rejects.toMatchObject({ status: 401, code: "invalid_token" });
+    expect(refresh).toHaveBeenCalledOnce();
+    expect(f.calls).toHaveLength(2);
+  });
+
+  test("resends the body on retry", async () => {
+    const f = fakeFetch(problem(401, "invalid_token"), json({ accepted: [], rejected: [] }));
+    const { api } = client(f);
+    await api.push([]);
+    expect(f.calls[1].body).toEqual({ records: [] });
+  });
+
+  test("doesn't refresh on 403 invalid_token", async () => {
+    const f = fakeFetch(problem(403, "invalid_token"));
+    const { api, refresh } = client(f);
+    await expect(api.listSnapshots()).rejects.toMatchObject({ status: 403, code: "invalid_token" });
+    expect(refresh).not.toHaveBeenCalled();
+  });
+
+  test("a refresh failure propagates", async () => {
+    const f = fakeFetch(problem(401, "invalid_token"));
+    const { api, refresh } = client(f);
+    refresh.mockRejectedValueOnce(Error("invalid_grant"));
+    await expect(api.listSnapshots()).rejects.toThrow("invalid_grant");
+  });
+});
diff --git a/tests/services/sync/auth.test.ts b/tests/services/sync/auth.test.ts
new file mode 100644
index 0000000..bbb9c51
--- /dev/null
+++ b/tests/services/sync/auth.test.ts
@@ -0,0 +1,242 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { Host } from "@/adapters";
+import {
+  getAccessToken,
+  pkceChallenge,
+  refreshAccessToken,
+  signIn,
+  signOut,
+  SyncAuthError,
+} from "@/services/sync/auth";
+import { keySyncAuth, keySyncState, type SyncAuth } from "@/services/sync/state";
+import { fakeLocalStorage, jsonResponse } from "../../helpers";
+
+const ORIGIN = "https://byte.vet";
+const REDIRECT = "https://abc.chromiumapp.org/oauth";
+const DISCOVERY = {
+  issuer: `${ORIGIN}/api/auth`,
+  authorization_endpoint: `${ORIGIN}/api/auth/oauth2/authorize`,
+  token_endpoint: `${ORIGIN}/api/auth/oauth2/token`,
+  revocation_endpoint: `${ORIGIN}/api/auth/oauth2/revoke`,
+  userinfo_endpoint: `${ORIGIN}/api/auth/oauth2/userinfo`,
+};
+
+let local: Record<string, unknown>;
+let session: Record<string, unknown>;
+let requests: { url: string; init?: RequestInit }[];
+let tokenReplies: (() => Response)[];
+
+const json = jsonResponse;
+
+const form = (init?: RequestInit) =>
+  Object.fromEntries(new URLSearchParams(String(init?.body)));
+
+beforeEach(() => {
+  local = fakeLocalStorage();
+  session = {};
+  requests = [];
+  tokenReplies = [];
+  vi.spyOn(Host, "getSession").mockImplementation(async (k) => session[k] as any);
+  vi.spyOn(Host, "setSession").mockImplementation(async (k, v) => {
+    session[k] = v;
+  });
+  vi.spyOn(Host, "getRedirectURL").mockReturnValue(REDIRECT);
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: string | URL, init?: RequestInit) => {
+      const url = String(input);
+      requests.push({ url, init });
+      if (url.endsWith("/.well-known/oauth-authorization-server")) {
+        return json(DISCOVERY);
+      }
+      if (url === DISCOVERY.token_endpoint) {
+        const reply = tokenReplies.shift();
+        if (!reply) throw Error("unexpected token request");
+        // let concurrent callers pile up behind the lock
+        await new Promise((r) => setTimeout(r, 5));
+        return reply();
+      }
+      if (url === DISCOVERY.userinfo_endpoint) {
+        return json({ sub: "user-1", email: "me@example.com" });
+      }
+      if (url === DISCOVERY.revocation_endpoint) return new Response(null);
+      throw Error(`unexpected fetch ${url}`);
+    })
+  );
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+/** The browser's auth flow: approve, and redirect with `extra` params. */
+function approveFlow(extra: (state: string) => Record<string, string>) {
+  return vi.spyOn(Host, "launchWebAuthFlow").mockImplementation(async (url) => {
+    const state = new URL(url).searchParams.get("state")!;
+    const ret = new URL(REDIRECT);
+    Object.entries(extra(state)).forEach(([k, v]) => ret.searchParams.set(k, v));
+    return ret.toString();
+  });
+}
+
+const tokens = (n: number) => () =>
+  json({ access_token: `access-${n}`, refresh_token: `refresh-${n}`, expires_in: 3600 });
+
+const signedIn = (overrides: Partial<SyncAuth> = {}): SyncAuth => ({
+  accessToken: "access-0",
+  refreshToken: "refresh-0",
+  expiresAt: Date.now() + 3_600_000,
+  account: { sub: "user-1", email: "me@example.com" },
+  ...overrides,
+});
+
+describe("signIn", () => {
+  test("runs the PKCE flow and stores the tokens and account", async () => {
+    const flow = approveFlow((state) => ({ code: "the-code", state }));
+    tokenReplies.push(tokens(1));
+
+    await signIn();
+
+    const authorize = new URL(flow.mock.calls[0][0]);
+    expect(Object.fromEntries(authorize.searchParams)).toMatchObject({
+      response_type: "code",
+      client_id: "proxyverse-extension",
+      redirect_uri: REDIRECT,
+      scope: "openid email offline_access sync",
+      code_challenge_method: "S256",
+    });
+    const exchange = requests.find((r) => r.url === DISCOVERY.token_endpoint)!;
+    const sent = form(exchange.init);
+    expect(sent).toMatchObject({
+      grant_type: "authorization_code",
+      code: "the-code",
+      redirect_uri: REDIRECT,
+      client_id: "proxyverse-extension",
+    });
+    expect(await pkceChallenge(sent.code_verifier)).toBe(
+      authorize.searchParams.get("code_challenge")
+    );
+    expect(local[keySyncAuth]).toMatchObject({
+      accessToken: "access-1",
+      refreshToken: "refresh-1",
+      account: { sub: "user-1", email: "me@example.com" },
+    });
+  });
+
+  test("rejects a redirect for another request", async () => {
+    approveFlow(() => ({ code: "c", state: "forged" }));
+    await expect(signIn()).rejects.toMatchObject({ code: "state_mismatch" });
+    expect(local[keySyncAuth]).toBeUndefined();
+  });
+
+  test("reports a denied or closed sign-in as cancelled", async () => {
+    approveFlow((state) => ({ error: "access_denied", state }));
+    await expect(signIn()).rejects.toMatchObject({ code: "cancelled" });
+
+    vi.spyOn(Host, "launchWebAuthFlow").mockRejectedValue(
+      Error("The user did not approve access.")
+    );
+    await expect(signIn()).rejects.toMatchObject({ code: "cancelled" });
+  });
+
+  test("starts sync over when another account signs in", async () => {
+    local[keySyncAuth] = signedIn({ expired: true, account: { sub: "someone-else" } });
+    local[keySyncState] = { cursor: 42 };
+    approveFlow((state) => ({ code: "c", state }));
+    tokenReplies.push(tokens(1));
+
+    await signIn();
+    expect(local[keySyncState]).toBeUndefined();
+  });
+
+  test("keeps the sync state when the same account signs in again", async () => {
+    local[keySyncAuth] = signedIn({ expired: true });
+    local[keySyncState] = { cursor: 42 };
+    approveFlow((state) => ({ code: "c", state }));
+    tokenReplies.push(tokens(1));
+
+    await signIn();
+    expect(local[keySyncState]).toEqual({ cursor: 42 });
+  });
+});
+
+test("no request to byte.vet sends cookies", async () => {
+  // the auth server refuses cookie-bearing POSTs (403 MISSING_OR_NULL_ORIGIN)
+  approveFlow((state) => ({ code: "c", state }));
+  tokenReplies.push(tokens(1));
+  await signIn();
+  local[keySyncAuth] = signedIn({ expiresAt: Date.now() });
+  tokenReplies.push(tokens(2));
+  await getAccessToken();
+  await signOut();
+
+  expect(requests.length).toBeGreaterThan(4);
+  for (const { url, init } of requests) {
+    expect(init?.credentials, url).toBe("omit");
+  }
+});
+
+describe("tokens", () => {
+  test("a fresh access token is used as is", async () => {
+    local[keySyncAuth] = signedIn();
+    expect(await getAccessToken()).toBe("access-0");
+    expect(requests).toHaveLength(0);
+  });
+
+  test("an expiring token is refreshed, and the rotated refresh token kept", async () => {
+    local[keySyncAuth] = signedIn({ expiresAt: Date.now() + 30_000 });
+    tokenReplies.push(tokens(1));
+
+    expect(await getAccessToken()).toBe("access-1");
+    const sent = form(requests.find((r) => r.url === DISCOVERY.token_endpoint)!.init);
+    expect(sent).toMatchObject({ grant_type: "refresh_token", refresh_token: "refresh-0" });
+    expect(local[keySyncAuth]).toMatchObject({ refreshToken: "refresh-1" });
+  });
+
+  test("concurrent refreshes spend the refresh token once", async () => {
+    local[keySyncAuth] = signedIn();
+    tokenReplies.push(tokens(1));
+
+    const got = await Promise.all([
+      refreshAccessToken("access-0"),
+      refreshAccessToken("access-0"),
+      refreshAccessToken("access-0"),
+    ]);
+    expect(got).toEqual(["access-1", "access-1", "access-1"]);
+    expect(requests.filter((r) => r.url === DISCOVERY.token_endpoint)).toHaveLength(1);
+  });
+
+  test("a refused refresh token expires the sign-in", async () => {
+    local[keySyncAuth] = signedIn();
+    tokenReplies.push(() => json({ error: "invalid_grant" }, 400));
+
+    await expect(refreshAccessToken("access-0")).rejects.toBeInstanceOf(SyncAuthError);
+    expect(local[keySyncAuth]).toMatchObject({ expired: true, refreshToken: "refresh-0" });
+    await expect(getAccessToken()).rejects.toMatchObject({ code: "signed_out" });
+  });
+
+  test("a server error keeps the sign-in", async () => {
+    local[keySyncAuth] = signedIn();
+    tokenReplies.push(() => json({ error: "temporarily_unavailable" }, 503));
+
+    await expect(refreshAccessToken("access-0")).rejects.toMatchObject({ code: "server" });
+    expect(local[keySyncAuth]).not.toHaveProperty("expired");
+  });
+});
+
+test("signOut revokes the refresh token and forgets the sign-in", async () => {
+  local[keySyncAuth] = signedIn();
+  local[keySyncState] = { cursor: 1 };
+
+  await signOut();
+
+  const revoke = requests.find((r) => r.url === DISCOVERY.revocation_endpoint)!;
+  expect(form(revoke.init)).toEqual({
+    token: "refresh-0",
+    token_type_hint: "refresh_token",
+    client_id: "proxyverse-extension",
+  });
+  expect(local[keySyncAuth]).toBeUndefined();
+  expect(local[keySyncState]).toBeUndefined();
+});
diff --git a/tests/services/sync/config.test.ts b/tests/services/sync/config.test.ts
new file mode 100644
index 0000000..ad87f48
--- /dev/null
+++ b/tests/services/sync/config.test.ts
@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { Host } from "@/adapters";
+import { SYNC_BUILD } from "@/services/sync/buildEnv";
+import { discover, syncFetch, syncOrigin } from "@/services/sync/config";
+import { jsonResponse } from "../../helpers";
+
+const ORIGIN = "https://sync.example";
+const metadata = {
+  issuer: `${ORIGIN}/api/auth`,
+  authorization_endpoint: `${ORIGIN}/api/auth/oauth2/authorize`,
+  token_endpoint: `${ORIGIN}/api/auth/oauth2/token`,
+  revocation_endpoint: `${ORIGIN}/api/auth/oauth2/revoke`,
+  userinfo_endpoint: `${ORIGIN}/api/auth/oauth2/userinfo`,
+  scopes_supported: ["openid", "sync"],
+  response_types_supported: ["code"],
+};
+
+/** Session storage backed by a map. */
+function fakeSession() {
+  const store = new Map<string, unknown>();
+  vi.spyOn(Host, "getSession").mockImplementation(async (k) => store.get(k) as never);
+  vi.spyOn(Host, "setSession").mockImplementation(async (k, v) => {
+    store.set(k, v);
+  });
+  return store;
+}
+
+const fetchReturning = (body: unknown, status = 200) =>
+  vi.fn(async () => jsonResponse(body, status)) as unknown as typeof fetch &
+    ReturnType<typeof vi.fn>;
+
+describe("syncOrigin", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  test("is the build's origin", async () => {
+    const get = vi.spyOn(Host, "get").mockResolvedValue("https://elsewhere");
+    expect(SYNC_BUILD.allowOriginOverride).toBe(false);
+    expect(await syncOrigin()).toBe(SYNC_BUILD.origin);
+    expect(get).not.toHaveBeenCalled();
+  });
+
+  test("e2e builds read an override from storage", async () => {
+    vi.spyOn(SYNC_BUILD, "allowOriginOverride", "get").mockReturnValue(true);
+    const get = vi.spyOn(Host, "get").mockResolvedValue("http://127.0.0.1:9000/");
+    expect(await syncOrigin()).toBe("http://127.0.0.1:9000");
+    expect(get).toHaveBeenCalledWith("sync.devOrigin");
+
+    get.mockResolvedValue(undefined);
+    expect(await syncOrigin()).toBe(SYNC_BUILD.origin);
+  });
+});
+
+describe("discover", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  test("fetches the metadata and caches it per origin", async () => {
+    const session = fakeSession();
+    const fetch = fetchReturning(metadata);
+    // only the endpoints are kept
+    const { response_types_supported: _, scopes_supported: __, ...expected } = metadata;
+
+    expect(await discover(ORIGIN, fetch)).toEqual(expected);
+    expect(fetch).toHaveBeenCalledWith(
+      `${ORIGIN}/.well-known/oauth-authorization-server`,
+      expect.anything()
+    );
+    expect(session.get("sync.discovery")).toEqual({ [ORIGIN]: expected });
+
+    expect(await discover(ORIGIN, fetch)).toEqual(expected);
+    expect(fetch).toHaveBeenCalledOnce();
+
+    // another origin isn't served from the cache
+    await expect(discover("https://other.example", fetch)).rejects.toThrow(/issuer/);
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+
+  test("rejects an issuer on another origin", async () => {
+    fakeSession();
+    const fetch = fetchReturning({ ...metadata, issuer: "https://evil.example/api/auth" });
+    await expect(discover(ORIGIN, fetch)).rejects.toThrow(/issuer/);
+  });
+
+  test.each([
+    "authorization_endpoint",
+    "token_endpoint",
+    "revocation_endpoint",
+    "userinfo_endpoint",
+  ])("requires %s", async (key) => {
+    const session = fakeSession();
+    const fetch = fetchReturning({ ...metadata, [key]: undefined });
+    await expect(discover(ORIGIN, fetch)).rejects.toThrow(key);
+    expect(session.size).toBe(0);
+  });
+
+  test("fails on an HTTP error", async () => {
+    fakeSession();
+    await expect(discover(ORIGIN, fetchReturning({}, 404))).rejects.toThrow(/404/);
+  });
+});
+
+test("requests to byte.vet never send its cookies", async () => {
+  // byte.vet refuses cookie-bearing cross-site POSTs (403 MISSING_OR_NULL_ORIGIN)
+  const fetch = vi.fn(async () => new Response("{}"));
+  vi.stubGlobal("fetch", fetch);
+  try {
+    await syncFetch("https://byte.vet/x", { method: "POST", credentials: "include" });
+    expect(fetch).toHaveBeenCalledWith("https://byte.vet/x", {
+      method: "POST",
+      credentials: "omit",
+    });
+  } finally {
+    vi.unstubAllGlobals();
+  }
+});
diff --git a/tests/services/sync/engine.test.ts b/tests/services/sync/engine.test.ts
new file mode 100644
index 0000000..86b7900
--- /dev/null
+++ b/tests/services/sync/engine.test.ts
@@ -0,0 +1,455 @@
+/// <reference types="node" />
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { ProfilesStorage, ProxyProfile } from "@/services/profile";
+import { SyncApi } from "@/services/sync/api";
+import { SyncEngine, type SyncDevice } from "@/services/sync/engine";
+import type { SyncedPref } from "@/services/sync/records";
+import {
+  DEFAULT_SYNC_SETTINGS,
+  type SyncSettings,
+  type SyncState,
+} from "@/services/sync/state";
+import { SyncStore } from "../../../e2e/servers/syncStore";
+import { proxyProfile as proxy } from "../../helpers";
+
+// Two devices sync through the mock server's store, with the real API
+// client. Time is a shared counter, so edit order is explicit.
+
+let store: SyncStore;
+let clock: number;
+let lockID = 0;
+
+const T0 = Date.UTC(2026, 9, 27);
+
+
+class FakeDevice implements SyncDevice {
+  data: { profiles: ProfilesStorage; prefs: Partial<Record<SyncedPref, unknown>> } = {
+    profiles: {},
+    prefs: {},
+  };
+  syncState?: SyncState;
+  syncSettings: SyncSettings = structuredClone(DEFAULT_SYNC_SETTINGS);
+  isSignedIn = true;
+  authRejected = 0;
+  revoked = 0;
+  engine: SyncEngine;
+
+  constructor() {
+    this.engine = this.newEngine();
+  }
+
+  /** A fresh engine on the same storage, like a restarted service worker. */
+  newEngine() {
+    const { access_token } = store.issueTokens();
+    return new SyncEngine({
+      device: this,
+      api: (deviceID) =>
+        new SyncApi({
+          origin: "https://byte.vet",
+          deviceID,
+          version: "2.0.0",
+          getAccessToken: async () => access_token,
+          refreshAccessToken: async () => access_token,
+          fetch: store.fetch,
+        }),
+      info: { version: "2.0.0", browser: "chrome", os: "mac" },
+      onAuthRejected: async () => void this.authRejected++,
+      onDeviceRevoked: async () => void this.revoked++,
+      now: () => clock,
+      lockName: `device-${lockID++}`,
+    });
+  }
+
+  sync(trigger: "manual" | "local" | "alarm" | "start" = "manual") {
+    return this.engine.run({ trigger });
+  }
+
+  async profiles() {
+    return structuredClone(this.data.profiles);
+  }
+  async updateProfiles(mutate: (p: ProfilesStorage) => void | Promise<void>) {
+    const next = structuredClone(this.data.profiles);
+    await mutate(next);
+    this.data.profiles = next;
+  }
+  async prefs() {
+    return structuredClone(this.data.prefs);
+  }
+  async setPref(key: SyncedPref, value: unknown) {
+    this.data.prefs[key] = value;
+  }
+  async state() {
+    return this.syncState && structuredClone(this.syncState);
+  }
+  async setState(s: SyncState) {
+    this.syncState = structuredClone(s);
+  }
+  async settings() {
+    return structuredClone(this.syncSettings);
+  }
+  async signedIn() {
+    return this.isSignedIn;
+  }
+
+  /**
+   * Edit while offline: the run that notices the edit (2 s later in the
+   * extension) dates it, but can't push it.
+   */
+  async editOffline(p: ProxyProfile) {
+    this.edit(p);
+    store.failNext({ status: 503, code: "unavailable", path: "/records" });
+    await this.sync("manual");
+  }
+
+  edit(p: ProxyProfile) {
+    clock += 1000;
+    this.data.profiles[p.profileID] = structuredClone(p);
+  }
+  remove(id: string) {
+    clock += 1000;
+    delete this.data.profiles[id];
+  }
+}
+
+const pushes = () => store.requests("/records", "POST").length;
+
+beforeEach(() => {
+  store = new SyncStore();
+  clock = T0;
+  store.setNow(T0 + 10 * 60_000); // server time is ahead: no clock_skew
+});
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("two devices", () => {
+  test("an edit on one device reaches the other", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.edit(proxy("p1"));
+    await a.sync();
+    await b.sync();
+    expect(b.data.profiles.p1).toEqual(proxy("p1"));
+
+    a.edit(proxy("p1", "10.9.9.9"));
+    await a.sync();
+    await b.sync("alarm");
+    expect(b.data.profiles.p1).toEqual(proxy("p1", "10.9.9.9"));
+  });
+
+  test("a deletion reaches the other device", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.edit(proxy("p1"));
+    await a.sync();
+    await b.sync();
+
+    b.remove("p1");
+    await b.sync();
+    await a.sync();
+    expect(a.data.profiles).toEqual({});
+    expect(store.get("profile:p1")).toMatchObject({ deleted: true, data: null });
+  });
+
+  test("the later edit wins, whichever device pushes first", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.edit(proxy("p1"));
+    await a.sync();
+    await b.sync();
+
+    await b.editOffline(proxy("p1", "10.0.0.2")); // earlier edit...
+    await a.editOffline(proxy("p1", "10.0.0.3")); // ...later edit
+    await a.sync(); // pushes the later one first
+    await b.sync(); // b's push is stale: it takes a's version
+    await a.sync();
+    expect(b.data.profiles.p1).toEqual(proxy("p1", "10.0.0.3"));
+    expect(a.data.profiles.p1).toEqual(proxy("p1", "10.0.0.3"));
+
+    await a.editOffline(proxy("p1", "10.0.0.4")); // earlier edit, pushed last
+    await b.editOffline(proxy("p1", "10.0.0.5"));
+    await b.sync();
+    await a.sync();
+    await b.sync();
+    expect(a.data.profiles.p1).toEqual(proxy("p1", "10.0.0.5"));
+    expect(b.data.profiles.p1).toEqual(proxy("p1", "10.0.0.5"));
+  });
+
+  test("a later edit beats an earlier deletion", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.edit(proxy("p1"));
+    await a.sync();
+    await b.sync();
+
+    a.remove("p1");
+    store.failNext({ status: 503, code: "unavailable", path: "/records" });
+    await a.sync();
+    await b.editOffline(proxy("p1", "10.0.0.7"));
+    await a.sync();
+    await b.sync();
+    await a.sync();
+    expect(a.data.profiles.p1).toEqual(proxy("p1", "10.0.0.7"));
+  });
+
+  test("preferences sync, unless a device turns them off", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.data.prefs["ui.actionBehavior"] = "sidebar";
+    await a.sync();
+    await b.sync();
+    expect(b.data.prefs["ui.actionBehavior"]).toBe("sidebar");
+
+    b.syncSettings.syncPrefs = false;
+    clock += 1000;
+    a.data.prefs["theme.darkmode"] = 1;
+    await a.sync();
+    await b.sync();
+    expect(b.data.prefs["theme.darkmode"]).toBeUndefined();
+  });
+});
+
+describe("first sync", () => {
+  async function accountWith(p: ProxyProfile) {
+    const a = new FakeDevice();
+    a.edit(p);
+    await a.sync();
+    return a;
+  }
+
+  test("a device with nothing of its own takes the account's data", async () => {
+    await accountWith(proxy("cloud"));
+    const b = new FakeDevice();
+    b.data.prefs["ui.language"] = "auto";
+    await b.sync();
+    expect(b.syncState?.needsFirstChoice).toBeUndefined();
+    expect(b.data.profiles.cloud).toEqual(proxy("cloud"));
+  });
+
+  test("asks when both sides have data, then merges", async () => {
+    const a = await accountWith(proxy("cloud"));
+    const b = new FakeDevice();
+    b.edit(proxy("mine"));
+    await b.sync();
+    expect(b.syncState?.needsFirstChoice).toBe(true);
+    expect(pushes()).toBe(1); // only a's
+
+    await b.engine.run({ trigger: "manual", firstChoice: "merge" });
+    await a.sync();
+    expect(Object.keys(b.data.profiles).sort()).toEqual(["cloud", "mine"]);
+    expect(Object.keys(a.data.profiles).sort()).toEqual(["cloud", "mine"]);
+  });
+
+  test("merge: this device's version wins a same-ID conflict", async () => {
+    await accountWith(proxy("p1", "10.0.0.1"));
+    const b = new FakeDevice();
+    b.edit(proxy("p1", "10.0.0.2"));
+    await b.sync();
+    await b.engine.run({ trigger: "manual", firstChoice: "merge" });
+    expect(store.get("profile:p1")?.data).toMatchObject(proxy("p1", "10.0.0.2"));
+  });
+
+  test("use cloud data: replaces this device's profiles", async () => {
+    await accountWith(proxy("cloud"));
+    const b = new FakeDevice();
+    b.edit(proxy("mine"));
+    await b.sync();
+    await b.engine.run({ trigger: "manual", firstChoice: "cloud" });
+    expect(Object.keys(b.data.profiles)).toEqual(["cloud"]);
+    expect(store.get("profile:mine")).toBeUndefined();
+  });
+
+  test("upload this device: replaces the account's data, after a snapshot", async () => {
+    const a = await accountWith(proxy("cloud"));
+    const b = new FakeDevice();
+    b.edit(proxy("mine"));
+    await b.sync();
+    await b.engine.run({ trigger: "manual", firstChoice: "upload" });
+    await a.sync();
+
+    expect(store.listSnapshots()[0]).toMatchObject({ reason: "before-overwrite" });
+    expect(store.get("profile:cloud")).toMatchObject({ deleted: true });
+    expect(Object.keys(a.data.profiles)).toEqual(["mine"]);
+  });
+});
+
+describe("bookkeeping", () => {
+  test("applying remote changes doesn't push them back", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.edit(proxy("p1"));
+    await a.sync();
+    await b.sync();
+
+    const before = pushes();
+    await b.sync("local"); // the storage event of its own write
+    await b.sync();
+    expect(pushes()).toBe(before);
+  });
+
+  test("a service worker wake syncs only when there's something to do", async () => {
+    const a = new FakeDevice();
+    await a.sync();
+    const requests = () => store.log.length;
+
+    // woken soon after a sync, nothing pending: no request at all
+    clock += 60_000;
+    const before = requests();
+    await a.sync("start");
+    expect(requests()).toBe(before);
+
+    // a change made while it slept is pushed
+    a.edit(proxy("p1"));
+    await a.sync("start");
+    expect(store.get("profile:p1")).toBeDefined();
+
+    // a poll's worth of time later, a wake pulls again
+    clock += 15 * 60_000;
+    const changesBefore = store.requests("/changes").length;
+    await a.sync("start");
+    expect(store.requests("/changes").length).toBeGreaterThan(changesBefore);
+  });
+
+  test("a pending change survives a failed run and a restart", async () => {
+    const a = new FakeDevice();
+    await a.sync();
+    a.edit(proxy("p1"));
+    store.failNext({ status: 503, code: "unavailable", retryAfter: 60, path: "/records" });
+    await a.sync();
+    expect(a.syncState?.lastSync?.error?.code).toBe("unavailable");
+    expect(a.syncState?.backoff?.until).toBe(clock + 60_000);
+
+    a.engine = a.newEngine();
+    await a.sync("alarm"); // still backing off
+    expect(store.get("profile:p1")).toBeUndefined();
+    await a.sync("manual"); // the user asked: try now
+    expect(store.get("profile:p1")?.data).toMatchObject(proxy("p1"));
+    expect(a.syncState?.backoff).toBeUndefined();
+  });
+
+  test("a local-only profile never leaves the device", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.syncSettings.localOnly = ["secret"];
+    a.edit(proxy("secret"));
+    a.edit(proxy("shared"));
+    await a.sync();
+    expect(store.get("profile:secret")).toBeUndefined();
+
+    // another device's profile with the same ID doesn't overwrite it
+    b.edit(proxy("secret", "10.6.6.6"));
+    await b.sync();
+    await a.sync();
+    expect(a.data.profiles.secret).toEqual(proxy("secret"));
+  });
+
+  test("marking a synced profile local-only leaves the cloud copy", async () => {
+    const a = new FakeDevice();
+    a.edit(proxy("p1"));
+    await a.sync();
+    a.syncSettings.localOnly = ["p1"];
+    a.remove("p1");
+    await a.sync();
+    expect(store.get("profile:p1")).toMatchObject({ deleted: false });
+  });
+
+  test("records of a newer schema are held, not applied or overwritten", async () => {
+    const a = new FakeDevice();
+    await a.sync();
+    store.seed([
+      { id: "profile:future", schema: "2099-01", data: { profileID: "future", proxyType: "warp" } },
+    ]);
+    await a.sync();
+    expect(a.data.profiles.future).toBeUndefined();
+    expect(a.syncState?.held["profile:future"]).toBeDefined();
+    expect(store.get("profile:future")?.schema).toBe("2099-01");
+  });
+
+  test("a record the server refuses isn't pushed again until it changes", async () => {
+    store.configure({ maxRecords: 1 });
+    const a = new FakeDevice();
+    a.edit(proxy("p1"));
+    a.edit(proxy("p2"));
+    await a.sync();
+    expect(Object.values(a.syncState?.failed ?? {})).toEqual([
+      expect.objectContaining({ reason: "quota_exceeded" }),
+    ]);
+
+    const before = pushes();
+    await a.sync();
+    expect(pushes()).toBe(before);
+  });
+
+  test("a device clock far ahead is reported", async () => {
+    const a = new FakeDevice();
+    await a.sync();
+    clock = T0 + 60 * 60_000; // an hour past the server
+    a.edit(proxy("p1"));
+    await a.sync();
+    expect(a.syncState?.lastSync?.error?.code).toBe("clock_skew");
+    expect(store.get("profile:p1")).toBeUndefined();
+  });
+
+  test("a resync after purged tombstones removes what was deleted elsewhere", async () => {
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.edit(proxy("p1"));
+    a.edit(proxy("p2"));
+    await a.sync();
+    await b.sync();
+
+    b.remove("p1");
+    await b.sync();
+    store.purgeTombstones();
+    a.edit(proxy("p3")); // a pending change survives the resync
+    await a.sync();
+
+    expect(Object.keys(a.data.profiles).sort()).toEqual(["p2", "p3"]);
+    expect(store.get("profile:p3")).toBeDefined();
+  });
+
+  test("a PAC URL profile syncs its URL; each device keeps its own script", async () => {
+    const pac = (data?: string): ProxyProfile => ({
+      profileID: "pac",
+      color: "#000000",
+      profileName: "pac",
+      proxyType: "pac",
+      pacScript: { sourceURL: "https://example.test/proxy.pac", data, lastFetched: 1 },
+    });
+    const a = new FakeDevice();
+    const b = new FakeDevice();
+    a.edit(pac("script on a"));
+    await a.sync();
+    expect(store.get("profile:pac")?.data).not.toHaveProperty("pacScript.data");
+
+    await b.sync();
+    expect(b.data.profiles.pac).toMatchObject({ pacScript: { sourceURL: "https://example.test/proxy.pac" } });
+    b.data.profiles.pac = pac("script on b"); // its fetcher ran
+
+    a.edit({ ...pac("script on a"), profileName: "renamed" });
+    await a.sync();
+    await b.sync();
+    expect(b.data.profiles.pac).toMatchObject({
+      profileName: "renamed",
+      pacScript: { data: "script on b" },
+    });
+  });
+
+  test("a revoked device and a refused token are reported", async () => {
+    const a = new FakeDevice();
+    await a.sync();
+    store.failNext({ status: 403, code: "invalid_token" });
+    await a.sync();
+    expect(a.authRejected).toBe(1);
+
+    store.revokeDevice(a.syncState!.deviceID);
+    await a.sync();
+    expect(a.revoked).toBe(1);
+  });
+
+  test("does nothing when signed out", async () => {
+    const a = new FakeDevice();
+    a.isSignedIn = false;
+    await a.sync();
+    expect(store.log).toHaveLength(0);
+  });
+});
diff --git a/tests/services/sync/hlc.test.ts b/tests/services/sync/hlc.test.ts
new file mode 100644
index 0000000..2d442f4
--- /dev/null
+++ b/tests/services/sync/hlc.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, test } from "vitest";
+import {
+  compareHLC,
+  formatHLC,
+  isHLC,
+  observeHLC,
+  parseHLC,
+  tickHLC,
+} from "@/services/sync/hlc";
+
+const DEV = "7b1e0000-0000-4000-8000-000000000001";
+
+describe("HLC format", () => {
+  test("formats with fixed widths and parses back", () => {
+    const hlc = formatHLC({ time: 1730023456789, counter: 3, deviceID: DEV });
+    expect(hlc).toBe(`001730023456789:0003:${DEV}`);
+    expect(isHLC(hlc)).toBe(true);
+    expect(parseHLC(hlc)).toEqual({
+      time: 1730023456789,
+      counter: 3,
+      deviceID: DEV,
+    });
+  });
+
+  test("rejects malformed clocks", () => {
+    expect(isHLC("1730023456789:0003:dev")).toBe(false);
+    expect(isHLC(`001730023456789:3:${DEV}`)).toBe(false);
+    expect(isHLC("001730023456789:0003:dev_1")).toBe(false);
+    expect(isHLC(`001730023456789:0003:${"a".repeat(65)}`)).toBe(false);
+    expect(isHLC(42)).toBe(false);
+    expect(parseHLC("nope")).toBeUndefined();
+    expect(() => formatHLC({ time: 1, counter: 1, deviceID: "a b" })).toThrow();
+    expect(() => formatHLC({ time: 1, counter: 10000, deviceID: "a" })).toThrow();
+    expect(() => formatHLC({ time: -1, counter: 0, deviceID: "a" })).toThrow();
+  });
+
+  test("string order is clock order", () => {
+    const hlcs = [
+      formatHLC({ time: 1000, counter: 0, deviceID: "b" }),
+      formatHLC({ time: 999, counter: 9999, deviceID: "z" }),
+      formatHLC({ time: 1000, counter: 0, deviceID: "a" }),
+      formatHLC({ time: 1000, counter: 1, deviceID: "a" }),
+      formatHLC({ time: 10000, counter: 0, deviceID: "a" }),
+    ];
+    const sorted = [...hlcs].sort(compareHLC).map((h) => parseHLC(h));
+    expect(sorted).toEqual([
+      { time: 999, counter: 9999, deviceID: "z" },
+      { time: 1000, counter: 0, deviceID: "a" },
+      { time: 1000, counter: 0, deviceID: "b" },
+      { time: 1000, counter: 1, deviceID: "a" },
+      { time: 10000, counter: 0, deviceID: "a" },
+    ]);
+    expect(compareHLC(hlcs[0], hlcs[0])).toBe(0);
+  });
+});
+
+describe("tickHLC", () => {
+  test("starts at the wall clock", () => {
+    expect(tickHLC(undefined, DEV, 5000)).toBe(
+      formatHLC({ time: 5000, counter: 0, deviceID: DEV })
+    );
+    expect(tickHLC("garbage", DEV, 5000)).toBe(
+      formatHLC({ time: 5000, counter: 0, deviceID: DEV })
+    );
+  });
+
+  test("counts edits within one millisecond", () => {
+    const a = tickHLC(undefined, DEV, 5000);
+    const b = tickHLC(a, DEV, 5000);
+    expect(parseHLC(b)).toMatchObject({ time: 5000, counter: 1 });
+    expect(compareHLC(b, a)).toBe(1);
+  });
+
+  test("stays monotonic when the clock goes backwards", () => {
+    let last = tickHLC(undefined, DEV, 10_000);
+    for (const now of [9_000, 5_000, 10_000, 9_999]) {
+      const next = tickHLC(last, DEV, now);
+      expect(compareHLC(next, last)).toBe(1);
+      expect(parseHLC(next)?.time).toBe(10_000);
+      last = next;
+    }
+    // the wall clock catching up resets the counter
+    expect(parseHLC(tickHLC(last, DEV, 10_001))).toMatchObject({
+      time: 10_001,
+      counter: 0,
+    });
+  });
+
+  test("moves to the next millisecond when the counter overflows", () => {
+    const full = formatHLC({ time: 5000, counter: 9999, deviceID: "x" });
+    const next = tickHLC(full, DEV, 5000);
+    expect(parseHLC(next)).toEqual({ time: 5001, counter: 0, deviceID: DEV });
+    expect(compareHLC(next, full)).toBe(1);
+  });
+
+  test("issues clocks after one seen from another device", () => {
+    const seen = formatHLC({ time: 9000, counter: 7, deviceID: "other" });
+    expect(parseHLC(tickHLC(seen, DEV, 1000))).toEqual({
+      time: 9000,
+      counter: 8,
+      deviceID: DEV,
+    });
+  });
+});
+
+describe("observeHLC", () => {
+  const older = formatHLC({ time: 1000, counter: 0, deviceID: "a" });
+  const newer = formatHLC({ time: 2000, counter: 0, deviceID: "b" });
+
+  test("keeps the later clock", () => {
+    expect(observeHLC(older, newer)).toBe(newer);
+    expect(observeHLC(newer, older)).toBe(newer);
+    expect(observeHLC(undefined, older)).toBe(older);
+  });
+
+  test("ignores an invalid received clock", () => {
+    expect(observeHLC(older, "bogus")).toBe(older);
+    expect(observeHLC(undefined, "bogus")).toBeUndefined();
+  });
+
+  test("the next tick follows the observed clock", () => {
+    const clock = observeHLC(older, newer);
+    expect(compareHLC(tickHLC(clock, DEV, 0), newer)).toBe(1);
+  });
+});
diff --git a/tests/services/sync/records.test.ts b/tests/services/sync/records.test.ts
new file mode 100644
index 0000000..1ca115b
--- /dev/null
+++ b/tests/services/sync/records.test.ts
@@ -0,0 +1,289 @@
+import { describe, expect, test } from "vitest";
+import type { ProxyProfile } from "@/services/profile";
+import { SystemProfile } from "@/services/profile";
+import {
+  PAYLOAD_SCHEMA,
+  canonicalJSON,
+  collectLocalRecords,
+  decodeRemote,
+  type ProfilePayload,
+  hashPayload,
+  isValidPrefValue,
+  mergeIncomingProfile,
+  normalizeProfile,
+  parseRecordID,
+  prefRecordID,
+  profileRecordID,
+} from "@/services/sync/records";
+
+const proxy: ProxyProfile = {
+  profileID: "p1",
+  profileName: "Office",
+  color: "#abcdef",
+  proxyType: "proxy",
+  proxyRules: {
+    default: {
+      scheme: "http",
+      host: "proxy.example",
+      port: 8080,
+      auth: { username: "u", password: "secret" },
+    },
+    bypassList: ["localhost"],
+  },
+};
+
+const pacURL: ProxyProfile = {
+  profileID: "pac1",
+  profileName: "Corp PAC",
+  color: "#112233",
+  proxyType: "pac",
+  pacScript: {
+    sourceURL: "https://corp.example/proxy.pac",
+    data: "function FindProxyForURL(){return 'DIRECT'}",
+    refreshIntervalMinutes: 30,
+    lastFetched: 1700000000000,
+    lastError: "timeout",
+  },
+};
+
+const pacInline: ProxyProfile = {
+  profileID: "pac2",
+  profileName: "Inline",
+  color: "#445566",
+  proxyType: "pac",
+  pacScript: { data: "function FindProxyForURL(){return 'DIRECT'}" },
+};
+
+describe("record IDs", () => {
+  test("name profiles and synced prefs", () => {
+    expect(profileRecordID("p1")).toBe("profile:p1");
+    expect(prefRecordID("ui.language")).toBe("pref:ui.language");
+    expect(parseRecordID("profile:a:b")).toEqual({
+      kind: "profile",
+      profileID: "a:b",
+    });
+    expect(parseRecordID("pref:theme.darkmode")).toEqual({
+      kind: "pref",
+      key: "theme.darkmode",
+    });
+    expect(parseRecordID("pref:active-profile")).toBeUndefined();
+    expect(parseRecordID("profile:")).toBeUndefined();
+    expect(parseRecordID("other:x")).toBeUndefined();
+  });
+
+  test("the payload schema is the config format", () => {
+    expect(PAYLOAD_SCHEMA).toBe("2025-01");
+  });
+});
+
+describe("pref payloads", () => {
+  test.each([
+    ["theme.darkmode", 0, true],
+    ["theme.darkmode", 2, true],
+    ["theme.darkmode", 3, false],
+    ["theme.darkmode", "1", false],
+    ["ui.language", "auto", true],
+    ["ui.language", "pt_BR", true],
+    ["ui.language", "fil", true],
+    ["ui.language", "pt-BR", false],
+    ["ui.language", "EN", false],
+    ["ui.actionBehavior", "sidebar", true],
+    ["ui.actionBehavior", "tab", false],
+  ] as const)("%s = %j valid: %s", (key, value, valid) => {
+    expect(isValidPrefValue(key, value)).toBe(valid);
+  });
+
+  test("decodes valid remote prefs only", () => {
+    expect(decodeRemote("pref:ui.language", { value: "zh_CN" })).toEqual({
+      value: "zh_CN",
+    });
+    expect(
+      decodeRemote("pref:ui.language", { value: "zh_CN", x: 1 })
+    ).toEqual({ value: "zh_CN" });
+    expect(decodeRemote("pref:ui.language", { value: 1 })).toBeUndefined();
+    expect(decodeRemote("pref:ui.language", null)).toBeUndefined();
+    expect(decodeRemote("pref:other", { value: 1 })).toBeUndefined();
+    expect(decodeRemote("profile:p1", { value: 1 })).toBeUndefined();
+  });
+});
+
+describe("normalizeProfile", () => {
+  test("upper-cases the color and keeps credentials", () => {
+    const payload = normalizeProfile(proxy);
+    expect(payload).toMatchObject({ color: "#ABCDEF", profileID: "p1" });
+    expect(payload).toHaveProperty("proxyRules.default.auth.password", "secret");
+  });
+
+  test("drops runtime fields and the fetched script of a PAC URL", () => {
+    expect(normalizeProfile(pacURL)).toEqual({
+      profileID: "pac1",
+      profileName: "Corp PAC",
+      color: "#112233",
+      proxyType: "pac",
+      pacScript: {
+        sourceURL: "https://corp.example/proxy.pac",
+        refreshIntervalMinutes: 30,
+      },
+    });
+  });
+
+  test("keeps an inline PAC script", () => {
+    expect(normalizeProfile(pacInline)).toHaveProperty(
+      "pacScript.data",
+      "function FindProxyForURL(){return 'DIRECT'}"
+    );
+  });
+
+  test("never mutates its input", () => {
+    const before = JSON.stringify([proxy, pacURL]);
+    const payload = normalizeProfile(proxy)!;
+    normalizeProfile(pacURL);
+    if (payload.proxyType === "proxy") payload.proxyRules.bypassList.push("x");
+    expect(JSON.stringify([proxy, pacURL])).toBe(before);
+  });
+
+  test("rejects system and invalid profiles", () => {
+    expect(normalizeProfile(SystemProfile.DIRECT)).toBeUndefined();
+    expect(
+      normalizeProfile({ ...proxy, color: "red" } as ProxyProfile)
+    ).toBeUndefined();
+  });
+});
+
+describe("hashing", () => {
+  test("canonical JSON sorts keys at every level, without whitespace", () => {
+    expect(
+      canonicalJSON({ b: 1, a: { d: [3, { z: 1, y: 2 }], c: "x" }, u: undefined })
+    ).toBe('{"a":{"c":"x","d":[3,{"y":2,"z":1}]},"b":1}');
+    expect(canonicalJSON({ 10: 1, 9: 2, a: 3 })).toBe('{"10":1,"9":2,"a":3}');
+    expect(canonicalJSON([undefined, null, "é"])).toBe('[null,null,"é"]');
+  });
+
+  test("equal payloads hash the same, whatever the key order", async () => {
+    const a = await hashPayload({ x: 1, y: [1, 2] });
+    expect(a).toMatch(/^[0-9a-f]{64}$/);
+    expect(await hashPayload({ y: [1, 2], x: 1 })).toBe(a);
+    expect(await hashPayload({ y: [2, 1], x: 1 })).not.toBe(a);
+  });
+
+  test("hashes the canonical JSON with SHA-256", async () => {
+    // printf '{"a":1,"b":2}' | shasum -a 256
+    expect(await hashPayload({ b: 2, a: 1 })).toBe(
+      "43258cff783fe7036d8a43033f830adfc60ec037382473548ac742b888292777"
+    );
+  });
+});
+
+describe("decodeRemote (profiles)", () => {
+  test("validates and normalizes a remote payload", () => {
+    expect(
+      decodeRemote("profile:pac1", { ...pacURL, color: "#aabbcc" })
+    ).toEqual(normalizeProfile({ ...pacURL, color: "#AABBCC" }));
+  });
+
+  test("requires the profile ID of the record", () => {
+    expect(decodeRemote("profile:other", proxy)).toBeUndefined();
+    expect(decodeRemote("pref:ui.language", proxy)).toBeUndefined();
+  });
+
+  test("rejects invalid payloads and system profiles", () => {
+    expect(
+      decodeRemote("profile:p1", { ...proxy, proxyType: "nope" })
+    ).toBeUndefined();
+    expect(decodeRemote("profile:p1", null)).toBeUndefined();
+    expect(
+      decodeRemote("profile:direct", SystemProfile.DIRECT)
+    ).toBeUndefined();
+  });
+});
+
+describe("mergeIncomingProfile", () => {
+  const remote = normalizeProfile(pacURL)!;
+
+  test("keeps the fetched script when the PAC URL is unchanged", () => {
+    expect(mergeIncomingProfile(remote, pacURL)).toEqual({
+      ...remote,
+      pacScript: {
+        ...(remote.proxyType === "pac" ? remote.pacScript : {}),
+        data: pacURL.proxyType === "pac" ? pacURL.pacScript.data : "",
+        lastFetched: 1700000000000,
+        lastError: "timeout",
+      },
+    });
+  });
+
+  test("leaves the script to fetch when the PAC URL changed", () => {
+    const moved = {
+      ...pacURL,
+      pacScript: { sourceURL: "https://old/", data: "old script" },
+    } as ProxyProfile;
+    const merged = mergeIncomingProfile(remote, moved);
+    expect(merged).toEqual(remote);
+    expect(merged).not.toHaveProperty("pacScript.data");
+  });
+
+  test("takes the remote as-is otherwise", () => {
+    const p = normalizeProfile(proxy)!;
+    expect(mergeIncomingProfile(p, pacURL)).toEqual(p);
+    expect(mergeIncomingProfile(remote)).toEqual(remote);
+    // a copy: storing it doesn't alias the payload
+    expect(mergeIncomingProfile(p)).not.toBe(p);
+  });
+});
+
+describe("collectLocalRecords", () => {
+  const profiles = {
+    p1: proxy,
+    pac1: pacURL,
+    local: { ...proxy, profileID: "local" },
+    bad: { ...proxy, profileID: "bad", color: "nope" },
+    direct: SystemProfile.DIRECT,
+    mismatched: { ...proxy, profileID: "elsewhere" },
+  } as Record<string, ProxyProfile>;
+  const prefs = {
+    "theme.darkmode": 1,
+    "ui.language": "not a language",
+    "ui.actionBehavior": "sidebar",
+  };
+
+  test("collects synced profiles and valid prefs, with their hashes", async () => {
+    const records = await collectLocalRecords({
+      profiles,
+      prefs,
+      localOnly: ["local"],
+      syncPrefs: true,
+    });
+    expect([...records.keys()].sort()).toEqual([
+      "pref:theme.darkmode",
+      "pref:ui.actionBehavior",
+      "profile:p1",
+      "profile:pac1",
+    ]);
+    const pac = records.get("profile:pac1")!;
+    expect(pac.payload).toEqual(normalizeProfile(pacURL));
+    expect(pac.hash).toBe(await hashPayload(pac.payload));
+    expect(records.get("pref:theme.darkmode")?.payload).toEqual({ value: 1 });
+  });
+
+  test("leaves prefs out when they don't sync", async () => {
+    const records = await collectLocalRecords({
+      profiles: {},
+      prefs,
+      localOnly: [],
+      syncPrefs: false,
+    });
+    expect(records.size).toBe(0);
+  });
+
+  test("a stored remote profile hashes like the remote payload", async () => {
+    const remote = decodeRemote("profile:pac1", pacURL) as ProfilePayload;
+    const stored = mergeIncomingProfile(remote, pacURL);
+    const records = await collectLocalRecords({
+      profiles: { pac1: stored },
+      prefs: {},
+      localOnly: [],
+      syncPrefs: true,
+    });
+    expect(records.get("profile:pac1")?.hash).toBe(await hashPayload(remote));
+  });
+});
diff --git a/tests/services/sync/state.test.ts b/tests/services/sync/state.test.ts
new file mode 100644
index 0000000..70c8af4
--- /dev/null
+++ b/tests/services/sync/state.test.ts
@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { reactive } from "vue";
+import { Host } from "@/adapters";
+import {
+  clearSyncAuth,
+  getSyncAuth,
+  getSyncSettings,
+  initialSyncState,
+  onSyncStorageChanged,
+  updateSyncSettings,
+  setSyncState,
+} from "@/services/sync/state";
+
+describe("sync state", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  test("a new device starts from scratch with a random ID", () => {
+    const a = initialSyncState();
+    expect(a).toEqual({
+      deviceID: expect.stringMatching(/^[0-9a-f-]{36}$/),
+      cursor: 0,
+      base: {},
+      local: {},
+      held: {},
+    });
+    expect(initialSyncState().deviceID).not.toBe(a.deviceID);
+  });
+
+  test("settings default to syncing prefs, nothing local-only", async () => {
+    vi.spyOn(Host, "get").mockResolvedValue(undefined);
+    expect(await getSyncSettings()).toEqual({ syncPrefs: true, localOnly: [] });
+    vi.spyOn(Host, "get").mockResolvedValue({ localOnly: ["p1"] });
+    expect(await getSyncSettings()).toEqual({ syncPrefs: true, localOnly: ["p1"] });
+  });
+
+  test("writes plain copies", async () => {
+    vi.spyOn(Host, "get").mockResolvedValue(undefined);
+    const set = vi.spyOn(Host, "set").mockResolvedValue();
+    const localOnly = reactive(["p1"]);
+    await updateSyncSettings((s) => (s.localOnly = localOnly));
+    const [key, value] = set.mock.calls[0];
+    expect(key).toBe("sync.settings");
+    expect(value).toEqual({ syncPrefs: true, localOnly: ["p1"] });
+    expect((value as { localOnly: unknown }).localOnly).not.toBe(localOnly);
+
+    const state = initialSyncState();
+    await setSyncState(state);
+    expect(set).toHaveBeenLastCalledWith("sync.state", state);
+  });
+
+  test("clearing removes the key", async () => {
+    const remove = vi.spyOn(Host, "remove").mockResolvedValue();
+    await clearSyncAuth();
+    expect(remove).toHaveBeenCalledWith("sync.auth");
+    vi.spyOn(Host, "get").mockResolvedValue(undefined);
+    expect(await getSyncAuth()).toBeUndefined();
+  });
+
+  test("reports changes of the sync keys only", () => {
+    let listener: (changes: Record<string, { newValue?: unknown }>) => void = () => {};
+    const unsubscribe = vi.fn();
+    vi.spyOn(Host, "onLocalStorageChanged").mockImplementation((l) => {
+      listener = l;
+      return unsubscribe;
+    });
+
+    const callback = vi.fn();
+    expect(onSyncStorageChanged(callback)).toBe(unsubscribe);
+
+    listener({ profiles: { newValue: {} } });
+    expect(callback).not.toHaveBeenCalled();
+    listener({ profiles: { newValue: {} }, "sync.state": { newValue: 1 }, "sync.auth": {} });
+    expect(callback).toHaveBeenCalledWith({ "sync.state": { newValue: 1 }, "sync.auth": {} });
+  });
+});
diff --git a/tests/services/sync/syncStore.test.ts b/tests/services/sync/syncStore.test.ts
new file mode 100644
index 0000000..56973e8
--- /dev/null
+++ b/tests/services/sync/syncStore.test.ts
@@ -0,0 +1,433 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  SyncProblem,
+  SyncStore,
+  formatHlc,
+  pkceChallenge,
+  type PushRecord,
+} from "../../../e2e/servers/syncStore";
+
+const NOW = 1_760_000_000_000;
+const DEV_A = "11111111-1111-4111-8111-111111111111";
+const DEV_B = "22222222-2222-4222-8222-222222222222";
+const ORIGIN = "http://sync.test";
+const CLIENT = "proxyverse-extension";
+const REDIRECT = "https://abcdef.chromiumapp.org/oauth";
+
+const hlc = (t: number, c = 0, dev = DEV_A) => formatHlc(t, c, dev);
+
+function profile(id: string, t = NOW, extra: Partial<PushRecord> = {}): PushRecord {
+  return {
+    id: `profile:${id}`,
+    hlc: hlc(t),
+    deleted: false,
+    schema: "2025-01",
+    encoding: "json",
+    data: { profileID: id, profileName: id, proxyType: "direct", color: "#FFFFFF" },
+    ...extra,
+  };
+}
+
+const pref = (key: string, value: unknown, t = NOW): PushRecord => ({
+  id: `pref:${key}`,
+  hlc: hlc(t),
+  deleted: false,
+  schema: "2025-01",
+  encoding: "json",
+  data: { value },
+});
+
+let store: SyncStore;
+beforeEach(() => {
+  store = new SyncStore();
+  store.setNow(NOW);
+});
+
+describe("push", () => {
+  it("stores new records with increasing revs", () => {
+    const res = store.push([profile("a"), profile("b")], DEV_A);
+    expect(res).toEqual({
+      accepted: [
+        { id: "profile:a", rev: 1 },
+        { id: "profile:b", rev: 2 },
+      ],
+      rejected: [],
+    });
+    expect(store.get("profile:a")).toMatchObject({ rev: 1, deviceID: DEV_A, deleted: false });
+  });
+
+  it("is last-writer-wins on the HLC", () => {
+    store.push([profile("a", NOW - 10)], DEV_A);
+    const newer = profile("a", NOW, { data: { profileID: "a", proxyType: "proxy" } });
+    expect(store.push([newer], DEV_B).accepted).toEqual([{ id: "profile:a", rev: 2 }]);
+    expect(store.get("profile:a")).toMatchObject({ rev: 2, hlc: newer.hlc, deviceID: DEV_B });
+  });
+
+  it("treats an equal HLC as already accepted, with the stored rev", () => {
+    store.push([profile("a"), profile("b")], DEV_A);
+    const res = store.push([profile("a")], DEV_A);
+    expect(res.accepted).toEqual([{ id: "profile:a", rev: 1 }]);
+    expect(store.currentRev()).toBe(2);
+  });
+
+  it("rejects an older HLC as stale with the stored record", () => {
+    store.push([profile("a", NOW)], DEV_A);
+    const res = store.push([profile("a", NOW - 1)], DEV_B);
+    expect(res.accepted).toEqual([]);
+    expect(res.rejected).toEqual([
+      { id: "profile:a", reason: "stale", current: store.get("profile:a") },
+    ]);
+  });
+
+  it("processes records on their own", () => {
+    const res = store.push([profile("direct"), profile("ok")], DEV_A);
+    expect(res.accepted).toEqual([{ id: "profile:ok", rev: 1 }]);
+    expect(res.rejected).toEqual([{ id: "profile:direct", reason: "reserved_id" }]);
+  });
+
+  it.each([
+    ["bad HLC", profile("a", NOW, { hlc: "123:0000:x" }), "invalid_record"],
+    ["HLC device with bad chars", profile("a", NOW, { hlc: formatHlc(NOW, 0, "a_b") }), "invalid_record"],
+    ["reserved direct", profile("direct"), "reserved_id"],
+    ["reserved system", profile("system"), "reserved_id"],
+    ["tombstone with data", profile("a", NOW, { deleted: true }), "invalid_record"],
+    ["live record without data", profile("a", NOW, { data: null }), "invalid_record"],
+    ["unknown schema", profile("a", NOW, { schema: "2099-01" }), "unknown_schema"],
+    ["unknown pref key", pref("theme.color", 1), "invalid_record"],
+    ["bad darkmode", pref("theme.darkmode", 3), "invalid_record"],
+    ["bad language", pref("ui.language", "EN"), "invalid_record"],
+    ["bad actionBehavior", pref("ui.actionBehavior", "tab"), "invalid_record"],
+    ["profileID mismatch", profile("a", NOW, { data: { profileID: "b", proxyType: "direct" } }), "invalid_record"],
+    ["proxyType missing", profile("a", NOW, { data: { profileID: "a" } }), "invalid_record"],
+    ["too large", profile("a", NOW, { data: { profileID: "a", proxyType: "pac", pad: "x".repeat(256 * 1024) } }), "too_large"],
+    ["clock skew", profile("a", NOW + 5 * 60 * 1000 + 1), "clock_skew"],
+  ])("rejects %s", (_name, rec, reason) => {
+    const res = store.push([rec], DEV_A);
+    expect(res.accepted).toEqual([]);
+    expect(res.rejected).toEqual([{ id: rec.id, reason }]);
+    expect(store.records()).toEqual([]);
+  });
+
+  it("accepts valid prefs and clock skew up to 5 minutes", () => {
+    const res = store.push(
+      [
+        pref("theme.darkmode", 2),
+        pref("ui.language", "zh_CN"),
+        pref("ui.actionBehavior", "sidebar"),
+        profile("a", NOW + 5 * 60 * 1000),
+      ],
+      DEV_A
+    );
+    expect(res.rejected).toEqual([]);
+    expect(res.accepted).toHaveLength(4);
+  });
+
+  it("stores unknown encodings opaquely, without schema validation", () => {
+    const rec = profile("a", NOW, { schema: "2099-01", encoding: "e2e-v1", data: "ciphertext" });
+    expect(store.push([rec], DEV_A).accepted).toEqual([{ id: "profile:a", rev: 1 }]);
+    expect(store.get("profile:a")?.data).toBe("ciphertext");
+  });
+
+  it("stores tombstones", () => {
+    store.push([profile("a", NOW - 1)], DEV_A);
+    store.push([profile("a", NOW, { deleted: true, data: null })], DEV_A);
+    expect(store.get("profile:a")).toMatchObject({ rev: 2, deleted: true, data: null });
+  });
+
+  it("rejects records over the account quota on their own, tombstones included", () => {
+    store.configure({ maxRecords: 2 });
+    store.push([profile("a"), profile("b", NOW, { deleted: true, data: null })], DEV_A);
+    const res = store.push([profile("c"), profile("a", NOW + 1)], DEV_A);
+    expect(res.rejected).toEqual([{ id: "profile:c", reason: "quota_exceeded" }]);
+    expect(res.accepted).toEqual([{ id: "profile:a", rev: 3 }]);
+
+    store.reset();
+    store.setNow(NOW);
+    store.configure({ maxBytes: 200 });
+    const big = { profileID: "x", proxyType: "pac", pad: "x".repeat(150) };
+    expect(store.push([profile("x", NOW, { data: big })], DEV_A).accepted).toHaveLength(1);
+    expect(store.push([profile("y", NOW, { data: { ...big, profileID: "y" } })], DEV_A).rejected).toEqual([
+      { id: "profile:y", reason: "quota_exceeded" },
+    ]);
+  });
+
+  it("refuses an empty or oversized batch", () => {
+    expect(() => store.push([], DEV_A)).toThrow(SyncProblem);
+    const many = Array.from({ length: 101 }, (_, i) => profile(`p${i}`));
+    expect(() => store.push(many, DEV_A)).toThrow(/invalid_request/);
+  });
+});
+
+describe("changes", () => {
+  beforeEach(() => {
+    store.push(["a", "b", "c", "d", "e"].map((id) => profile(id)), DEV_A);
+  });
+
+  it("pages by rev with a cursor", () => {
+    const p1 = store.changes(0, 2);
+    expect(p1.records.map((r) => r.rev)).toEqual([1, 2]);
+    expect(p1).toMatchObject({ cursor: 2, hasMore: true });
+    const p2 = store.changes(p1.cursor, 2);
+    expect(p2.records.map((r) => r.rev)).toEqual([3, 4]);
+    const p3 = store.changes(p2.cursor, 2);
+    expect(p3.records.map((r) => r.rev)).toEqual([5]);
+    expect(p3).toMatchObject({ cursor: 5, hasMore: false });
+  });
+
+  it("returns max(since, rev) as the cursor when there is nothing new", () => {
+    expect(store.changes(5)).toEqual({ records: [], cursor: 5, hasMore: false });
+    expect(store.changes(9)).toEqual({ records: [], cursor: 9, hasMore: false });
+  });
+
+  it("defaults the limit to 500 and caps it at 1000", () => {
+    store.seed(Array.from({ length: 1100 }, (_, i) => ({ id: `profile:s${i}`, data: {} })));
+    expect(store.changes(0).records).toHaveLength(500);
+    expect(store.changes(0, 5000).records).toHaveLength(1000);
+  });
+
+  it("answers 410 cursor_expired below the purged rev, but allows a full resync", () => {
+    store.push([profile("a", NOW + 1, { deleted: true, data: null })], DEV_A); // rev 6
+    store.push([profile("b", NOW + 1)], DEV_A); // rev 7
+    expect(store.purgeTombstones()).toBe(6);
+    expect(store.get("profile:a")).toBeUndefined();
+    expect(() => store.changes(5)).toThrow(expect.objectContaining({ status: 410, code: "cursor_expired" }));
+    expect(store.changes(6).records.map((r) => r.rev)).toEqual([7]);
+    expect(store.changes(0).records.map((r) => r.id)).not.toContain("profile:a");
+  });
+});
+
+describe("snapshots", () => {
+  it("lists newest first, with reasons", () => {
+    store.push([profile("a")], DEV_A);
+    store.createSnapshot(DEV_A, "manual");
+    store.setNow(NOW + 1000);
+    store.createSnapshot(DEV_A, "before-overwrite");
+    expect(store.listSnapshots().map((s) => s.reason)).toEqual(["before-overwrite", "manual"]);
+    expect(store.listSnapshots()[0]).toMatchObject({ rev: 1, recordCount: 1, createdBy: DEV_A });
+  });
+
+  it("restores with a server HLC above every stored one, tombstoning extra records", () => {
+    store.push([profile("a"), profile("b")], DEV_A);
+    const snap = store.createSnapshot(DEV_A);
+    // a device with a clock ahead of the server (within the skew window)
+    const ahead = NOW + 60_000;
+    store.push([profile("a", ahead, { data: { profileID: "a", proxyType: "proxy" } }), profile("c")], DEV_B);
+
+    const res = store.restore(snap.id, DEV_A);
+    expect(res).toEqual({ rev: 7, written: 3 });
+    const serverHlc = formatHlc(ahead + 1, 0, "server");
+    expect(store.get("profile:a")).toMatchObject({ rev: 5, hlc: serverHlc, deleted: false, data: { proxyType: "direct" } });
+    expect(store.get("profile:b")).toMatchObject({ rev: 6, hlc: serverHlc });
+    expect(store.get("profile:c")).toMatchObject({ rev: 7, hlc: serverHlc, deleted: true, data: null });
+    expect(store.listSnapshots()[0]).toMatchObject({ reason: "before-restore", recordCount: 3 });
+  });
+
+  it("floors the restore HLC at now", () => {
+    store.push([profile("a", NOW - 100_000)], DEV_A);
+    const snap = store.createSnapshot(DEV_A);
+    store.restore(snap.id, DEV_A);
+    expect(store.get("profile:a")?.hlc).toBe(formatHlc(NOW, 0, "server"));
+  });
+
+  it("404s an unknown snapshot", () => {
+    expect(() => store.getSnapshot("nope")).toThrow(expect.objectContaining({ status: 404 }));
+  });
+});
+
+describe("oauth", () => {
+  const verifier = "v".repeat(43);
+  function authorize(challenge = pkceChallenge(verifier), scope = "openid email offline_access sync") {
+    const url = new URL(
+      store.authorize({
+        client_id: CLIENT,
+        redirect_uri: REDIRECT,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state: "st",
+        scope,
+      })
+    );
+    expect(url.origin + url.pathname).toBe(REDIRECT);
+    expect(url.searchParams.get("state")).toBe("st");
+    return url.searchParams.get("code")!;
+  }
+  const exchange = (code: string, v = verifier) =>
+    store.token({ grant_type: "authorization_code", code, redirect_uri: REDIRECT, client_id: CLIENT, code_verifier: v });
+  const refresh = (token: string) =>
+    store.token({ grant_type: "refresh_token", refresh_token: token, client_id: CLIENT });
+
+  it("exchanges a code with PKCE, once", () => {
+    const code = authorize();
+    const tokens = exchange(code);
+    expect(tokens).toMatchObject({ token_type: "Bearer", expires_in: 3600, scope: "openid email offline_access sync" });
+    expect(tokens.refresh_token).toBeTruthy();
+    expect(store.userinfo(tokens.access_token)).toEqual(store.user);
+    expect(() => exchange(code)).toThrow(/invalid_grant/);
+  });
+
+  it("rejects a PKCE mismatch", () => {
+    expect(() => exchange(authorize(), "w".repeat(43))).toThrow(/invalid_grant/);
+  });
+
+  it("rejects unknown clients and redirect URIs, and requires S256", () => {
+    expect(() => store.authorize({ client_id: "other", redirect_uri: REDIRECT })).toThrow(/invalid_client/);
+    expect(() => store.authorize({ client_id: CLIENT, redirect_uri: "https://evil.example/oauth" })).toThrow(
+      /invalid_request/
+    );
+    const url = new URL(store.authorize({ client_id: CLIENT, redirect_uri: REDIRECT, code_challenge: "x", code_challenge_method: "plain" }));
+    expect(url.searchParams.get("error")).toBe("invalid_request");
+    expect(store.authorize({ client_id: CLIENT, redirect_uri: "https://x.extensions.allizom.org/oauth", code_challenge: "x", code_challenge_method: "S256" })).toContain("code=");
+  });
+
+  it("gives no refresh token without offline_access", () => {
+    expect(exchange(authorize(undefined, "openid sync")).refresh_token).toBeUndefined();
+  });
+
+  it("rotates refresh tokens; reusing a spent one revokes the family", () => {
+    const first = exchange(authorize());
+    const second = refresh(first.refresh_token!);
+    expect(second.refresh_token).not.toBe(first.refresh_token);
+    const third = refresh(second.refresh_token!);
+
+    expect(() => refresh(first.refresh_token!)).toThrow(/invalid_grant/);
+    // the whole family is gone, including the newest tokens
+    expect(() => refresh(third.refresh_token!)).toThrow(/invalid_grant/);
+    expect(() => store.userinfo(third.access_token)).toThrow(/invalid_token/);
+  });
+
+  it("expires access tokens", () => {
+    const tokens = exchange(authorize());
+    store.setNow(NOW + 3600 * 1000);
+    expect(() => store.userinfo(tokens.access_token)).toThrow(/invalid_token/);
+    store.setNow(NOW);
+    const fresh = refresh(tokens.refresh_token!);
+    store.expireAccessTokens();
+    expect(() => store.userinfo(fresh.access_token)).toThrow(/invalid_token/);
+  });
+
+  it("revokes a refresh token and its access tokens", () => {
+    const tokens = exchange(authorize());
+    store.revoke(tokens.refresh_token!);
+    expect(() => store.userinfo(tokens.access_token)).toThrow(/invalid_token/);
+    expect(() => refresh(tokens.refresh_token!)).toThrow(/invalid_grant/);
+  });
+});
+
+describe("http dispatch", () => {
+  let access: string;
+  const headers = (device = DEV_A) => ({
+    authorization: `Bearer ${access}`,
+    "x-proxyverse-device": device,
+    "x-proxyverse-version": "2.3.0",
+    "content-type": "application/json",
+  });
+  const api = (path: string, init: RequestInit = {}, device = DEV_A) =>
+    store.fetch(`${ORIGIN}/api/proxyverse/v1${path}`, { ...init, headers: { ...headers(device), ...init.headers } });
+
+  beforeEach(() => {
+    access = store.issueTokens().access_token;
+  });
+
+  it("serves discovery metadata", async () => {
+    const res = await store.fetch(`${ORIGIN}/.well-known/oauth-authorization-server`);
+    expect(await res.json()).toMatchObject({
+      issuer: `${ORIGIN}/api/auth`,
+      token_endpoint: `${ORIGIN}/api/auth/oauth2/token`,
+      code_challenge_methods_supported: ["S256"],
+    });
+  });
+
+  it("runs the authorize → token flow over HTTP", async () => {
+    const verifier = "a".repeat(64);
+    const q = new URLSearchParams({
+      response_type: "code",
+      client_id: CLIENT,
+      redirect_uri: REDIRECT,
+      scope: "openid email offline_access sync",
+      code_challenge: pkceChallenge(verifier),
+      code_challenge_method: "S256",
+      state: "xyz",
+    });
+    const auth = await store.fetch(`${ORIGIN}/api/auth/oauth2/authorize?${q}`, { redirect: "manual" });
+    expect(auth.status).toBe(302);
+    const code = new URL(auth.headers.get("location")!).searchParams.get("code")!;
+    const tok = await store.fetch(`${ORIGIN}/api/auth/oauth2/token`, {
+      method: "POST",
+      body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: REDIRECT, client_id: CLIENT, code_verifier: verifier }),
+    });
+    expect(tok.status).toBe(200);
+    const bad = await store.fetch(`${ORIGIN}/api/auth/oauth2/token`, {
+      method: "POST",
+      body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: REDIRECT, client_id: CLIENT, code_verifier: verifier }),
+    });
+    expect(bad.status).toBe(400);
+    expect(await bad.json()).toMatchObject({ error: "invalid_grant" });
+  });
+
+  it("requires auth and headers", async () => {
+    let res = await store.fetch(`${ORIGIN}/api/proxyverse/v1/changes?since=0`);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("content-type")).toBe("application/problem+json");
+    expect(await res.json()).toMatchObject({ status: 401, code: "invalid_token", type: expect.stringContaining("#invalid_token") });
+
+    res = await api("/changes", { headers: { "x-proxyverse-device": "nope" } });
+    expect(res.status).toBe(400);
+
+    access = store.issueTokens(["openid"]).access_token;
+    expect((await api("/changes")).status).toBe(403);
+  });
+
+  it("pushes and pulls", async () => {
+    const res = await api("/records", { method: "POST", body: JSON.stringify({ records: [profile("a")] }) });
+    expect(await res.json()).toEqual({ accepted: [{ id: "profile:a", rev: 1 }], rejected: [] });
+    const changes = await (await api("/changes?since=0")).json();
+    expect(changes).toMatchObject({ cursor: 1, hasMore: false, records: [{ id: "profile:a", deviceID: DEV_A }] });
+    expect(store.requests("/records", "POST")).toHaveLength(1);
+  });
+
+  it("registers devices implicitly and revokes them", async () => {
+    await api("/changes?since=0", {}, DEV_B);
+    const put = await api(`/devices/${DEV_A}`, { method: "PUT", body: JSON.stringify({ name: "Chrome" }) });
+    expect(await put.json()).toMatchObject({ id: DEV_A, name: "Chrome", browser: null });
+    const list = await (await api("/devices")).json();
+    expect(list.map((d: { id: string }) => d.id).sort()).toEqual([DEV_A, DEV_B]);
+
+    expect((await api(`/devices/${DEV_B}`, { method: "DELETE" })).status).toBe(204);
+    const revoked = await api("/changes?since=0", {}, DEV_B);
+    expect(revoked.status).toBe(403);
+    expect(await revoked.json()).toMatchObject({ code: "device_revoked" });
+  });
+
+  it("creates snapshots (201) and restores them", async () => {
+    store.seed([{ id: "profile:a", data: { profileID: "a", proxyType: "direct" } }]);
+    const created = await api("/snapshots", { method: "POST", body: JSON.stringify({ reason: "before-overwrite" }) });
+    expect(created.status).toBe(201);
+    const meta = await created.json();
+    expect(meta).toMatchObject({ reason: "before-overwrite", recordCount: 1, createdBy: DEV_A });
+    expect(await (await api(`/snapshots/${meta.id}`)).json()).toMatchObject({ records: [{ id: "profile:a" }] });
+    const restored = await api(`/snapshots/${meta.id}/restore`, { method: "POST" });
+    expect(await restored.json()).toEqual({ rev: 2, written: 1 });
+    expect((await (await api("/snapshots")).json())[0].reason).toBe("before-restore");
+  });
+
+  it("fails the next matching request once, with Retry-After", async () => {
+    store.failNext({ status: 429, code: "rate_limited", retryAfter: 7, path: "/changes" });
+    expect((await api("/devices")).status).toBe(200);
+    const res = await api("/changes?since=0");
+    expect(res.status).toBe(429);
+    expect(res.headers.get("retry-after")).toBe("7");
+    expect(await res.json()).toMatchObject({ code: "rate_limited", status: 429 });
+    expect((await api("/changes?since=0")).status).toBe(200);
+  });
+
+  it("answers 410 over HTTP", async () => {
+    store.seed([{ id: "profile:a", deleted: true }, { id: "profile:b", data: {} }]);
+    store.purgeTombstones();
+    expect(store.changes(0).records).toHaveLength(1);
+    store.seed([{ id: "profile:c", deleted: true }]);
+    store.purgeTombstones();
+    const res = await api("/changes?since=2");
+    expect(res.status).toBe(410);
+    expect(await res.json()).toMatchObject({ code: "cursor_expired" });
+  });
+});
diff --git a/tsconfig.json b/tsconfig.json
index f279bac..a63c9a3 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -31,11 +31,7 @@
     "src/**/*.ts",
     "src/**/*.tsx",
     "src/**/*.vue",
-    "tests/**/*.ts"
-  ],
-  "references": [
-    {
-      "path": "./tsconfig.node.json"
-    }
+    "tests/**/*.ts",
+    "build/**/*.ts"
   ]
 }
\ No newline at end of file
diff --git a/tsconfig.node.json b/tsconfig.node.json
index 97ede7e..7af521f 100644
--- a/tsconfig.node.json
+++ b/tsconfig.node.json
@@ -1,11 +1,19 @@
 {
   "compilerOptions": {
-    "composite": true,
     "skipLibCheck": true,
     "module": "ESNext",
     "moduleResolution": "bundler",
     "allowSyntheticDefaultImports": true,
-    "strict": true
+    "strict": true,
+    "target": "ES2022",
+    "lib": [
+      "ES2022"
+    ],
+    "noEmit": true,
+    "allowImportingTsExtensions": true
   },
-  "include": ["vite.config.ts"]
+  "include": [
+    "vite.config.ts",
+    "build/**/*.ts"
+  ]
 }
diff --git a/vite.config.ts b/vite.config.ts
index e9e8cda..76a7f47 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -8,68 +8,27 @@ import Components from "unplugin-vue-components/vite";
 import { ArcoResolver } from "unplugin-vue-components/resolvers";
 import { visualizer } from "rollup-plugin-visualizer";
 import { createRequire } from "module";
+import { readFileSync } from "fs";
+import { parseBuildEnv, syncDefines } from "./build/env.ts";
+import { buildManifest, crxVersion, needsDevKey } from "./build/manifest.ts";
 
 // Use createRequire instead of `import manifest from "./manifest.json"` to
 // work around a Rolldown panic on nested member expressions of JSON imports.
 const manifest = createRequire(import.meta.url)("./manifest.json");
 
-const env = process.env;
+const PROXYVERSE_ENV = parseBuildEnv(process.env.PROXYVERSE_ENV);
+const CRX_VERSION = crxVersion(process.env.CRX_VER);
 
-const getCRXVersion = () => {
-  const crxVer = env.CRX_VER;
-  if (crxVer) {
-    let ver = crxVer;
-    if (ver.startsWith("v")) {
-      ver = ver.slice(1);
-    }
-    return ver.slice(0, 14);
-  }
-  return "0.0.0-dev";
-};
-
-// Workaround: Rolldown (Vite 8) panics on nested member expressions like
-// `manifest.background.service_worker` during config transformation.
-// Hoist `manifest.background` into a local variable to flatten the access.
-const manifestBg = manifest.background;
-
-function transformManifestForFirefox() {
-  manifestBg.scripts = [manifestBg.service_worker];
-  delete manifestBg.service_worker;
-
-  delete (manifest as any).version_name;
-
-  // Firefox has a sidebar instead of Chrome's side panel
-  delete (manifest as any).side_panel;
-  manifest.permissions = manifest.permissions.filter((p) => p !== "sidePanel");
-  (manifest as any).sidebar_action = {
-    default_panel: "index.html#/sidebar",
-    default_icon: "mini-logo.png",
-    open_at_install: false,
-  };
-
-  (manifest as any).browser_specific_settings = {
-    gecko: {
-      id: "proxyverse@byte.vet",
-      strict_min_version: "115.0",
-    },
-  };
-}
-
-type Transformer = {
-  manifest(): void;
-};
-
-const TRANSFORMER_CONFIG: Record<string, Transformer> = {
-  firefox: {
-    manifest: transformManifestForFirefox,
-  },
-};
+// the dev public key, read only by builds that need it (see build/README.md)
+const readDevKey = () =>
+  readFileSync(resolve(import.meta.dirname, "build/dev-extension-key.pub"), "utf8").trim();
 
 // https://vitejs.dev/config/
 export default defineConfig(({ mode }) => {
-  const transformer = TRANSFORMER_CONFIG[mode];
+  const target = mode === "firefox" ? "firefox" : "chrome";
 
   return {
+    define: syncDefines(PROXYVERSE_ENV),
     plugins: [
       vue(),
       AutoImport({
@@ -91,17 +50,18 @@ export default defineConfig(({ mode }) => {
               chunk.isEntry &&
               chunk.name == "background",
           );
-          manifest.version = getCRXVersion().split("-", 1)[0];
-          manifest.version_name = getCRXVersion();
-          // avoid cache issues
-          manifestBg.service_worker = (entry as any).fileName;
-
-          transformer?.manifest();
+          const built = buildManifest(manifest, {
+            mode: target,
+            env: PROXYVERSE_ENV,
+            version: CRX_VERSION,
+            serviceWorker: (entry as any).fileName,
+            devKey: needsDevKey(target, PROXYVERSE_ENV) ? readDevKey() : undefined,
+          });
 
           this.emitFile({
             type: "asset",
             fileName: "manifest.json",
-            source: JSON.stringify(manifest, undefined, 2),
+            source: JSON.stringify(built, undefined, 2),
           });
         },
       },