Skip to content

Encrypted sync design (no code) - #10

Merged
iamrraj merged 1 commit into
mainfrom
docs/sync-design
Aug 25, 2026
Merged

iamrraj merged 1 commit into
mainfrom
docs/sync-design

Conversation

@iamrraj

@iamrraj iamrraj commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Design only — nothing implemented. Companion to #9 (Travel Mode), which depends on this landing first.

Transport was chosen from what an extension page can actually do, probed rather than assumed:

showSaveFilePicker   function      chrome.identity   undefined
FileSystemFileHandle function      launchWebAuthFlow undefined

chrome.identity is absent because the manifest never requested it. So the recommendation is a file the user picks inside a folder their machine already syncs — iCloud Drive, Dropbox, OneDrive, Syncthing. That adds no OAuth, no tokens, no manifest permission and no network request at all: the syncing is done by software they already trust with their files, and KeyVault never learns which provider it is.

The hard part is the merge, and the model is closer to ready than expected. Deletions are already soft, and so is archiving — both are tombstones rather than absences. A hard delete is unmergeable, because a missing entry cannot be told apart from one that never arrived. The trash built for undo turns out to be what makes sync correct.

Three things are missing and specified here: a watermark of the last agreed state, a device identity, and a per-entry revision counter. The counter matters because wall-clock ordering across machines is not trustworthy — one laptop with a wrong clock would silently win every conflict forever.

Conflicts produce both versions, never a winner. Any rule that picks one — newest, longest, local — silently deletes somebody's password some of the time. A visible duplicate is an annoyance; a lost password is a support request that cannot be answered.

Recommends shipping Phase 1 alone: a manual Sync now button, which is automated encrypted backup into a folder that already leaves the machine.

Three open questions at the end.

Sync is the largest remaining gap and the feature most likely to lose data,
because it is the first where two copies of the truth exist at once.

Transport was chosen from what an extension page can actually do, probed
rather than assumed: showSaveFilePicker and FileSystemFileHandle are
available, chrome.identity is not — the manifest never asked for it. So the
recommendation is a file the user picks inside a folder their machine
already syncs. That adds no OAuth, no tokens, no manifest permission and no
network request at all: the syncing is done by software they already trust
with their files, and KeyVault never learns which provider it is.

The hard part is the merge, and the model turns out to be closer to ready
than expected. Deletions are already soft, and archiving is too, so both are
tombstones rather than absences — a hard delete is unmergeable, because a
missing entry cannot be told apart from one that never arrived. The trash
built for undo is what makes sync correct.

Three things are missing and are specified here: a watermark of the last
agreed state, a device identity, and a per-entry revision counter. The
counter matters because wall-clock ordering across machines is not
trustworthy — one laptop with a wrong clock would silently win every
conflict forever.

Conflicts produce both versions, never a winner. Any rule that picks one —
newest, longest, local — silently deletes somebody's password some of the
time. A visible duplicate is an annoyance; a lost password is a support
request that cannot be answered.

Recommends shipping Phase 1 alone: a manual Sync now button, which is
automated encrypted backup into a folder that already leaves the machine.
@iamrraj
iamrraj merged commit 1ce12cc into main Aug 25, 2026
5 checks passed
@iamrraj
iamrraj deleted the docs/sync-design branch August 25, 2026 11:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant