FerryKey protocol
How FerryKey keeps bookmarks and passwords in sync without our server being able to read them. It’s detailed enough to check our claims, or to write your own client.
Contents
- Overview and trust model
- Versions and support
- Keys
- Encrypted blobs (the envelope)
- Signatures
- Membership log
- Syncing a collection
- Data formats
- Live updates (MQTT)
- Writing your own client
- Changes
1. Overview and trust model
Actors
- Recovery words (the root). 24 words that encode a 256-bit random secret. Every account key that can be recovered comes from them. They are used to create the account, to add a device, to recover, and to override a stolen device. Devices forget them straight after use.
- Devices. Each browser extension or app install makes its own random signing key (Ed25519) and its own key pair for receiving data keys (HPKE with ML-KEM-768 + X25519). Private device keys never leave the device.
- Server.
api.ferrykey.comstores the membership log, signed heads and encrypted blobs.mqtt.ferrykey.comsends “something changed” notices. The server holds no secret that could decrypt anything.
Collections
An account’s data is split into collections. Each collection has its own key and its own history. The current collections are:
bookmarks: the bookmark tree.meta: device names, so the device list can show “Work laptop” instead of a key fingerprint.vault: FerryKey Passwords. Only devices that turned passwords on hold this key. The browser extensions never do.
A collection name is 1 to 32 characters of a-z, 0-9 and -, starting with a letter. The name log is reserved (live updates use it for the membership log). An account has at most 16 collections.
Trust model
We assume the server may be malicious. Clients must verify everything they receive. If they do, the server can’t:
- read any bookmark, password or device name (they are encrypted with keys it never sees);
- forge or change data, or move a blob to another account, collection or position (blobs are authenticated and bound to their location);
- add a device, or hide a lock-out by showing an older device list (the membership log is signed and hash-chained, and devices refuse a log that doesn’t extend the one they last saw);
- pass off data from a removed device or an old key (signed heads and snapshot statements name the log point they were made under, and right after a lock-out the remaining devices take the removed device’s data only as vouched for by the device that locked it out: see Lock out a device);
- quietly drop or rewrite history (heads are signed and hash-chained).
The server can still:
- refuse service, or withhold new data or new log entries from a device (a freeze);
- on a device’s very first sync, show it an older but genuine state (trust on first use);
- show different devices different branches of history (a fork). Each device checks that what it sees extends what it saw before, but devices don’t compare heads with each other;
- get in data a removed device signs in the moment between its removal and the seal that follows it (normally well under a second). If a lock-out stops before its seal is stored (or was made by an app version without seals), the other devices wait, and whoever finishes it later vouches for what the server holds by then: our apps finish it on the locking-out device’s next sync, and the recovery words can too;
- help a locked-out device decrypt any blob still stored from the key epochs that device held keys for;
- see metadata, listed below and per call in the API reference.
Anyone with your 24 words, or an unlocked device of yours, can read your data. A locked-out device keeps whatever it already downloaded.
What the server sees
| Sees | Never sees |
|---|---|
| Account ID (a hash of the root public key) | The 24 words or anything derived from them except public keys |
| Public keys of the root, recovery key and every device | Private keys of any device |
| Device IDs, which collections each device may use, and when devices were added or removed | Device names (encrypted in meta) |
| Collection names, commit numbers, times, and blob sizes rounded up to 1 KiB | Bookmarks, URLs, titles, folders, passwords, notes or any other content |
| When each device last made a request (to the hour), and the network address of each connection | Collection keys (only wrapped copies it can’t open) |
The API keeps no IP addresses. For the signup limit it stores a keyed hash of the network (IPv4 /24 or IPv6 /64) and the day.
2. Versions and support
The current protocol version is 2. Every API request names the version it speaks in the X-Fk-Protocol header. The /v1/ in API paths is the path prefix, not the protocol version: protocol 2 uses /v1/ paths. Signed objects also carry their own version (heads have "Version": 2).
Support policy
- The server supports the current version and the one before it, for at least 12 months after a new version is published. Old requests are converted to the current form inside the server, so old clients keep working unchanged.
- Additive changes don’t get a new version: new optional fields, new response fields, new endpoints. Clients must ignore JSON fields they don’t know. When a client rewrites a stored document (for example a vault entry), it should keep fields it doesn’t know.
- One exception: if a security flaw in an old version would put users’ data at risk, that version can be retired sooner. This has happened once. Protocol 1 let a malicious server roll back the device list, slip in data signed by removed devices or old keys, and drop commits when a device jumped to a snapshot. Protocol 2 fixed all three, and protocol 1 was retired the day protocol 2 shipped. Today only protocol 2 is supported.
How you’ll know
- The Changes list at the bottom of this page, dated.
- An HTTP response header on calls that use a version due to be retired. This is planned: the server will send the standard
DeprecationandSunsetheaders. It doesn’t send them yet. - Once support ends, the server answers every API call from that version with HTTP 409 and the code
upgrade_required. A request withoutX-Fk-Protocolcounts as protocol 1.
Frozen values
Every label string on this page (they all start with ferrykey v1 or ferrykey v2) is frozen. Changing one would change every user’s keys or invalidate every signature, so they never change. The “v1” or “v2” inside a label names that label’s format, not the protocol version. New cryptography would get new labels and a new protocol version.
3. Keys
Recovery secret and words
- The recovery secret is 32 bytes from a cryptographically secure random generator.
- It is shown as 24 words from the standard BIP39 English list (2048 words; the file’s SHA-256 is
2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda, one word per line with a trailing newline). - Encoding: append the first byte of SHA-256(secret) to the secret (264 bits), split into 24 groups of 11 bits, most significant bit first. Each group is a word index.
- Parsing ignores letter case and accepts any whitespace between words. It rejects unknown words, a word count other than 24, and a bad checksum.
- Not a BIP39 seed. The secret is the BIP39 entropy itself. There is no PBKDF2 step and no passphrase.
- The same secret can also be written as a kit code (used for the QR code):
ferrykey:v1:followed by the secret in RFC 4648 base32, upper case, no padding (52 characters). Parsing ignores case and surrounding whitespace.
Derivation
All derivations use HKDF-SHA256 (RFC 5869) with no salt (equivalent to 32 zero bytes) and the label as the info string, in ASCII.
| Key | Input | Info label | Length |
|---|---|---|---|
| Account master key (AMK) | recovery secret | ferrykey v1 account master key | 32 |
| Root signing key seed | AMK | ferrykey v1 account signing key | 32 |
| Recovery key seed | AMK | ferrykey v1 recovery kem seed | 64 |
| Reserved, unused | AMK | ferrykey v1 collection key: + collection name | 32 |
- Root signing key: the Ed25519 (RFC 8032) key whose 32-byte seed is the value above.
- Account ID: SHA-256 of the account’s first 32-byte root public key (the one in the Init entry), first 20 bytes, RFC 4648 base32 without padding, lower case. Always 32 characters. It never changes, even when the words are replaced.
- Recovery key: an HPKE key pair (RFC 9180) for the KEM
MLKEM768-X25519(KEM ID0x647a, also called X-Wing, as implemented by Go’scrypto/hpkefrom the IETF hpke-pq draft). Public keys are the ML-KEM-768 encapsulation key (1184 bytes) followed by the X25519 public key (32 bytes): 1216 bytes. The key pair is made from the 64-byte recovery key seedikmbyDeriveKeyPair:
The 32-byteseed = SHAKE256(ikm | "HPKE-v1" | "KEM" | 0x647a (u16) | u16 len("DeriveKeyPair") | "DeriveKeyPair" | u16 32), first 32 bytes expand: SHAKE256(seed) gives 64 bytes, the ML-KEM-768 seed (d | z), then 32 bytes, the X25519 private keyseedis the private key. Check your implementation against the recovery key vector. - Collection keys are random. The data keys are not derived from the words. Each key epoch draws a fresh random 32-byte key per collection and wraps it to every device and to the recovery key (see Membership). The words reach the data through the recovery key. The “collection key” label is reserved and not used for data.
Device keys
- An Ed25519 signing key pair, random.
- An HPKE
MLKEM768-X25519key pair, random. Its private key is stored as its 32-byte seed. - Device ID: computed from the device’s Ed25519 public key exactly like the account ID (32 lower-case base32 characters). The special signer ID
rootmeans the recovery words.
4. Encrypted blobs (the envelope)
Every piece of collection data on the server is one envelope: a commit’s change, or a snapshot of the whole collection. All integers are big-endian.
offset size field
0 3 magic "FKE" (46 4b 45)
3 1 version 0x01
4 1 algorithm 0x01
5 4 key epoch (u32)
9 32 salt (random, fresh for every blob)
41 n+16 AES-256-GCM ciphertext of the padded plaintext, then the 16-byte tag
Key and nonce
HKDF-SHA256(ikm = collection key for that epoch, salt = the 32-byte salt, info = "ferrykey v1 envelope message key", length 44). The first 32 bytes are the AES-256 key, the last 12 bytes the GCM nonce. A fresh key and nonce per blob means the usual limit on random GCM nonces doesn’t apply.
Associated data
The AAD binds the blob to where it lives:
"ferrykey v1 envelope aad" 24 bytes, no length prefix
header the first 41 bytes of the blob
u32 len(accountID) | accountID
u32 len(collection) | collection
kind 1 byte: 1 = change, 2 = snapshot (3 is reserved)
seq u64
For a change, seq is the commit’s number. For a snapshot, it is the number of the last commit the snapshot includes (0 for an empty collection). The epoch in the header must be the epoch of the key used. Readers must reject a blob whose header epoch isn’t the one they expect.
Padding
Before encryption the plaintext P becomes u32 len(P) | P | zero bytes, padded to a whole number of 1024-byte blocks. So a blob is 41 + 1024 × ceil((4 + len(P)) / 1024) + 16 bytes. The server sees only the padded size. When opening, reject a padded length that isn’t a multiple of 1024 or a length prefix larger than the data.
The plaintext is JSON (see Data formats). The server takes blobs of at most 5 MiB (5,242,880 bytes).
5. Signatures
All signatures are Ed25519 over a byte string. Each kind of signed message starts with its own label, and every variable-length field is length-prefixed, so a signature for one thing can never be read as another.
Notation used below: str(x) is u32 len(x) | x (bytes or UTF-8 text). strs(list) is u32 count followed by str of each item. u32 and u64 are big-endian. Hashes are raw 32 bytes. Labels are encoded with str() here (unlike the envelope AAD).
API requests
str("ferrykey v1 request")
str(method) "POST"
str(host) "api.ferrykey.com"
str(pathQuery) the request path, plus "?query" if there is one, e.g. "/v1/pull"
str(accountID)
str(deviceID) a device ID, or "root"
u64 timestamp unix seconds
nonce 16 random bytes, new for every request
SHA-256(body) of the exact body bytes sent
Sent in headers: X-Fk-Account, X-Fk-Device, X-Fk-Time (decimal), X-Fk-Nonce (32 hex characters) and X-Fk-Signature (128 hex characters). The host is always api.ferrykey.com, whatever address you connect to. The timestamp must be within 5 minutes of the server’s clock. Each nonce can be used once per account (the server remembers it for at least 10 minutes), so never retry a request with the same nonce: sign it again.
Heads (commits)
A head is a device’s signed pointer to one commit. Version 2 heads:
str("ferrykey v2 head")
str(accountID)
str(collection)
u64 seq this commit's number (the first commit is 1)
entryHash SHA-256 of the commit's envelope blob
prev hash of the head at seq-1; 32 zero bytes when seq is 1
u64 logSeq length of the membership log the device acted under
logHash hash of that log's last entry
u32 epoch key epoch of the blob (the log's epoch at logSeq)
str(deviceID)
u64 time unix seconds, informational
The head hash, used for prev and by snapshot statements, is SHA-256(message | u32 len(sig) | sig), so it covers the signature too.
Every head must also satisfy: Version is 2, and prev is zero exactly when seq is 1. Reject any head with another version.
Snapshot statements
A snapshot is signed by the device (or the recovery words) that uploaded it:
str("ferrykey v2 snapshot")
str(accountID)
str(collection)
u64 seq the head the snapshot is at (0 for an empty collection)
headHash hash of the head at seq; zero when seq is 0
blobHash SHA-256 of the snapshot's envelope blob
u64 logSeq
logHash
u32 epoch
str(signerID) a device ID, or "root"
u64 time
Membership entries and device proofs
See Membership log for their encodings.
6. Membership log
Each account has one append-only, hash-chained log of signed entries. Replaying it from the first entry gives the account’s current state: its root key, recovery key, collections, member devices, removed devices and current key epoch, plus the current epoch’s wrapped keys. The server replays it too, and refuses requests from non-members. Nobody needs a secret to check it.
Entry fields and signed message
str("ferrykey v1 membership entry")
str(accountID)
u64 seq 1 for the first entry
prev hash of entry seq-1; zero for seq 1
u64 time unix seconds, informational
str(signer) "root" or a member's device ID
op 1 byte: 1 Init, 2 Add, 3 Remove, 4 Epoch, 5 RotateRoot
str(rootPub) Init, RotateRoot (else empty)
str(recoveryKEM) Init, RotateRoot (else empty)
device 0x00 if absent, else 0x01 | str(signPub) | str(kemPub) | strs(collections) | str(proof)
str(deviceID) Remove (else empty)
u32 epoch Init/Epoch: the new epoch; Add/RotateRoot: the current one; Remove: 0
strs(collections) Init, Epoch (else empty)
u32 number of wraps, then for each: str(recipient) | str(collection) | str(ct)
The entry hash is SHA-256(message | u32 len(sig) | sig). The signer signs with the root key (signer root) or its device key.
Device proof. An Add carries the new device’s proof that it holds its signing key: its own signature over str("ferrykey v1 device key proof") | str(accountID) | str(signPub) | str(kemPub) | strs(collections).
Key wraps
A wrap is one 32-byte collection key encrypted to one recipient (a device ID, or recovery for the recovery key) with HPKE base mode, single shot: KEM MLKEM768-X25519, KDF HKDF-SHA256, AEAD AES-256-GCM, empty AAD, and
info = str("ferrykey v1 epoch key wrap") | str(accountID) | u32 epoch | str(collection) | str(recipient)
ct is the encapsulated key (1120 bytes) followed by the ciphertext and tag (48 bytes): exactly 1168 bytes.
Rules for each entry
An entry is valid only if all of these hold. Clients and the server apply the same rules.
- Chain. The first entry is an Init with seq 1 and a zero
prev. Every later entry has seq one more than the last,prevequal to the last entry’s hash, the same account ID, and is not an Init. - Signer. Init is signed by
root, its account ID must equal the account ID of itsrootPub, and it is checked against that key. Otherrootentries are checked against the current root key. RotateRoot may only be signed byroot. Any other signer must be a current member, and is refused while the account is root-locked (below). - Exact fields. Each op sets exactly the fields listed above and leaves the others empty.
- Collections lists have 1 to 16 valid names, sorted (byte order) and without duplicates.
- Keys. Ed25519 public keys must be 32 bytes, canonical, not the identity and not of small order. KEM public keys must parse as
MLKEM768-X25519public keys. - Wraps must be exactly the set required below, each 1168 bytes, with no extras or duplicates.
- Scope. A device may only act within its own collections. The root may do anything.
| Op | Rules | Wraps required |
|---|---|---|
| 1 Init | Epoch 1. Sets root key, recovery key and collections. | recovery × every collection |
| 2 Add | Device keys valid, proof valid, its collections a subset of the account’s and of the signer’s. Epoch = current. The device ID is neither a member nor ever removed (IDs are never reused). Refused while a rotation is pending. | new device × each of its collections, current epoch |
| 3 Remove | Target is a current member whose collections are within the signer’s. No wraps. Sets “rotation pending”. If signed by root, also sets the root lock. | none |
| 4 Epoch | Epoch = current + 1. Collections must include every existing one (new ones may be added). Signer’s scope must cover all of them, so only the root or a device holding every collection can rotate. Clears “rotation pending”. If signed by root, clears the root lock. | recovery × every collection, plus each member × each of its collections |
| 5 RotateRoot | Root only. New root key (one never used before on this account) and new recovery key. Epoch = current. The account ID stays the same. Sets “rotation pending” and the root lock. | new recovery key × every collection, current epoch |
Root lock. When the words remove a device or replace themselves, only the words may act until they sign an Epoch. This stops a thief’s devices from re-adding each other while the owner removes them.
Server limit: the server also refuses an Add when the account already has 20 devices.
Common flows
- Create an account. Generate the secret and show the words. Build an Init (epoch 1, random collection keys wrapped to the recovery key). Make device keys and an Add for this device, signed by
root. Send both with a proof of work to/v1/account. - Add a device with the words. Derive the root key and recovery key. Read the log, signing requests as
root. Unwrap the current keys from therecoverywraps. If a rotation is pending, the root lock is set, or this device needs a collection the account lacks, rotate first (below). Make device keys, then append an Add signed byroot. Forget the words. - Lock out a device. Append a Remove. Then at once seal every collection the removed device could write: pull it, and upload a snapshot of its current content at the current head, still in the current epoch, with a statement naming the log including the Remove. The seal vouches for what the removed device wrote before it was removed; other devices take nothing of its after that (see the reading checks below). Then rotate, if you hold every collection. A device that doesn’t can remove a device within its scope, but leaves the rotation to one that does, which rotates from the seal. If anything fails after the Remove, finish the seal and rotation the same way later. Our clients do this by themselves: while a rotation is pending, a device that signed a Remove since the latest rotation reads each collection as a new device would, and if it meets the removed device’s unvouched data, it seals (and rotates, if it can).
- Rotate. Read every collection with the current keys. Append an Epoch entry with fresh random keys. Then, for every collection that already existed, upload a snapshot of its current content sealed under the new epoch, at the current head. Until that snapshot exists the server refuses new commits to the collection (
snapshot_required), so new devices can always read the history. - Replace the words. Append a RotateRoot signed with the old words, then rotate in case the old words leaked.
While a rotation is pending the server refuses commits (rotation_required), but takes snapshots in the current epoch (the seal). Any write in the old epoch is refused once a new epoch starts.
7. Syncing a collection
Each collection is a numbered chain of commits. Commit n is an envelope (kind 1, seq n) holding a change, plus a version 2 head signed by the device that wrote it. Now and then a device uploads a snapshot: the whole content at some commit, sealed as kind 2 at that seq, with a signed statement. A device catching up starts from the latest snapshot and applies the commits after it.
Writing
- Read and verify the log. Pull and verify the collection up to the server’s head.
- Merge your local edits with what you pulled (a three-way merge against the last state you synced).
- Seal the change at seq = head + 1 in the log’s current epoch. Sign a version 2 head naming the current log length and hash, and
prev= hash of the head you pulled. - Post it to
/v1/commit. Onconflictorlog_changed, someone else got in first: pull, merge and try again with a fresh signature. - Our clients upload a snapshot after 32 commits since the last one. Commits and snapshots superseded by a newer snapshot are deleted within about 7 days, so snapshots keep pulls short.
What a client must check when reading
This is what stops a malicious server. Our implementation does all of it.
- Log. Replay the whole log from entry 1 with the rules above, and check its account ID is yours. Remember the log length and last-entry hash you last accepted. Refuse a log that is shorter, or whose entry at that position has a different hash (a rollback).
- Never write with an old key. If you hold a key for an epoch newer than the log’s current epoch, the log was rolled back: refuse to write.
- Head numbers. Refuse a pull whose
HeadSeqis below the commit you last synced, or a snapshot below what you already have. - Every head.
Versionis 2. Account and collection match. ItslogSeqmust exist in the log with thatlogHash. The signer must have been a member at that point, allowed this collection, andepochmust be the log’s epoch at that point and the blob’s header epoch. The signature must verify. It must link to the previous head (seq+ 1 andprev= previous head hash), andentryHashmust equal SHA-256 of the blob. - No going back. Keep a floor: the highest log point named by any head or statement you’ve accepted for this collection, and store it. A later head or statement may not name an earlier point.
- Nothing from before the latest rotation. Let R be the log position of the entry that started the current epoch (the Init or the latest Epoch). Commits you apply as data, and snapshot statements, must name a log point at or after R. A snapshot statement from before R by a device that is still a member is the seal of a rotation whose own snapshot hasn’t arrived yet: retry shortly.
- A removed device’s data needs a voucher. For a device removed after R (its rotation is still pending), don’t apply a change it signed, a snapshot it signed, or a snapshot reached by skipping heads it signed, unless that snapshot’s statement names a log point at or after its Remove (the seal). Its heads name a log point from before its removal either way, so they can’t show when it signed them. Retry shortly instead: the seal or the rotation is on its way. Only the device that signed the Remove, while it seals or rotates, and
roottake such data, because they are about to vouch for it. A device that removed itself is exempt. Anything of the removed device’s after a seal names an earlier log point than the floor, so it is tampering. - Snapshot statements. Every snapshot must have one: reject a snapshot without it. Account, collection, seq, head hash (of the snapshot’s anchor head) and blob hash must match. The signer must have been a member allowed this collection at the named point, or be
root(checked against the root key at that point). Epochs must match as for heads. - No gaps across a snapshot jump. When you trust head T and the server sends a snapshot at S > T, it first sends the signed heads T+1 to S−1. Check they link from T to the snapshot’s anchor head. If you trust a head at S already, the anchor must be identical to it (otherwise the server is showing you a fork). On a device’s first sync, ask for no skipped heads. The anchor head and the snapshot statement are still verified in full; there is just nothing earlier to link them to (trust on first use).
- Pull structure. Commits must be contiguous, starting right after what you have, and each commit’s
Head.Seqmust equal itsSeq. When a snapshot comes,Commits[0]must be its anchor, at exactly the snapshot’s seq (except for a snapshot at seq 0). Skipped heads with no snapshot after them in a response whoseMoreis false mean tampering. When a pull ends, the last head you verified must be the head of the last commit you applied. - Decrypt with the exact location. Open each blob with your account ID, the collection, the right kind, the commit or snapshot seq and the header’s epoch. Any failure means tampering.
- Validate the content. Apply each change and check the result is a valid document (see Data formats). Refuse anything invalid.
Rotation in progress. A rotation appends the Epoch entry first and uploads the new snapshots after it. So if the newest log entry is an Epoch and a collection has no snapshot in that epoch yet, a rotation is probably still running. Don’t apply a change whose head names a log point before the latest Epoch; retry shortly instead of reporting tampering. If the rotating device stopped before uploading, any device that holds the collection’s new key may finish it: when its newest data is still in an older epoch and it hasn’t seen a snapshot in the current one, it uploads a snapshot of what it has. Our clients do both.
Save, per collection: the synced content, its seq, the last trusted head, the keys you’ve unwrapped (by epoch, so older blobs still open), the floor, and the log length and hash.
8. Data formats
Envelope plaintexts are UTF-8 JSON. A commit holds a change. A snapshot holds the whole document.
Bookmarks (bookmarks)
A tree of nodes. Every node has a random sync ID (ours are 10 random bytes in upper-case base32, 16 characters; treat IDs as opaque strings). Four fixed root folders always exist and can’t be moved, renamed or deleted: toolbar, menu (Firefox’s bookmarks menu; others keep it untouched), other and mobile. Kinds: 1 folder, 2 bookmark, 3 separator. A folder’s child list is its order.
Snapshot (whole tree), with nodes sorted by ID:
{"nodes":[
{"id":"K5QX3M2PZ7RTA4BC","k":1,"t":"Reading","c":["M3VQ7Z2KD6LWE5PA"]},
{"id":"M3VQ7Z2KD6LWE5PA","k":2,"t":"Example","u":"https://example.com/"},
{"id":"menu","k":1},{"id":"mobile","k":1},{"id":"other","k":1},
{"id":"toolbar","k":1,"c":["K5QX3M2PZ7RTA4BC"]}],
"tombs":{"Q2L7...":{"Fingerprint":[97,123,...],"DeletedAt":1790000000000}}}
id, k kind, t title, u URL (bookmarks only), c child IDs (folders only). A valid tree has all four roots as folders, every other node reachable from a root exactly once, a URL on every bookmark and on nothing else, and children only on folders.
Tombstones remember deletions, so a device that missed one (or a browser’s own sync putting a bookmark back) doesn’t upload it again. Fingerprint is SHA-256 of one kind byte followed by the URL (bookmarks) or the title (folders and separators), as a JSON array of 32 numbers. DeletedAt is unix milliseconds. An unknown browser bookmark matching a tombstone deleted at or after the bookmark’s own creation time is a stale copy, and is removed rather than uploaded.
Change (one commit). Note the field names inside add and update are long:
{"add":[{"ID":"K5QX3M2PZ7RTA4BC","Kind":1,"Title":"Reading","URL":"","Children":null},
{"ID":"M3VQ7Z2KD6LWE5PA","Kind":2,"Title":"Example","URL":"https://example.com/","Children":null}],
"children":{"K5QX3M2PZ7RTA4BC":["M3VQ7Z2KD6LWE5PA"],"toolbar":["K5QX3M2PZ7RTA4BC"]}}
{"children":{"K5QX3M2PZ7RTA4BC":[]},
"delete":["M3VQ7Z2KD6LWE5PA"],
"tombs":{"M3VQ7Z2KD6LWE5PA":{"Fingerprint":[97,123,163,...],"DeletedAt":1790000000000}}}
Fields, all optional: add (new nodes, without children), update (new title and URL for existing nodes), children (the full new child list of every folder whose children changed), delete (every removed node, subtrees included), tombs (tombstones added or changed) and untomb (tombstones dropped). Roots may not be added, updated or deleted.
Apply a change in exactly this order, or devices will diverge: (1) add, (2) update, (3) delete, (4) children, folder by folder in sorted folder-ID order, (5) remove references to deleted nodes from every folder’s child list, (6) tombs, (7) untomb. Then validate the whole tree, and refuse the change if anything fails.
Merging. Our merge is deterministic so devices converge: a change on one side only is kept; if both sides changed the same field, the side already on the server wins; an edit or move beats a delete; the side that reordered a folder wins its order; a move that would make a cycle is undone; tombstones from all sides are kept except for nodes that survived. Your client may merge differently, but it must always produce a valid tree.
Device names (meta)
The same tree format. Each device adds a bookmark node under other whose ID is its device ID, whose title is its display name and whose URL is ferrykey:device. A device without one shows as “Unnamed device”.
Passwords (vault)
The whole document is encrypted. The server sees nothing inside it, only the padded blob size, which roughly reveals how many items are stored. Document:
{"items":{"q3k7m2xz5p4wb6tn5rcy2hjd":{"type":"login","title":"Example","user":"alex",
"pass":"correct horse","urls":["https://example.com/login"],
"created":1790000000000,"mod":1790000000000}},
"folders":{"imported":{"name":"Imported","mod":0}}}
| Item field | Meaning |
|---|---|
type | login, note, card, identity or sshkey |
f | folder ID; absent means imported |
title, user, pass, notes | text |
urls, tags | lists of text |
totp | an otpauth:// URI |
fields | custom fields: {"name","value","concealed","section"} |
fav | favourite (true or absent) |
src | where the item came from, e.g. import:chrome; display only |
created, mod, trash | unix milliseconds; mod is set by the device that changed the item; trash absent or 0 means not in the trash |
A folder is {"name","mod","trash"}. The folder imported (named “Imported” until renamed) always exists and can’t be deleted. Item and folder IDs are 1 to 64 characters of a-z, 0-9, - and _ (ours are 24 random base32 characters). Limits: 50,000 items and 1,000 folders. An item put by a change may be at most 256 KiB as JSON (checked when a change is applied, not when a snapshot is loaded).
Change: {"put":{id: item}, "del":[ids], "folders":{id: folder}, "delFolders":[ids]}, all optional. Items and folders are always replaced whole. Apply del, then put, then delFolders, then folders, then check the limits. Merging is per item and per field: the side with the newer mod wins, and for content the losing version is kept as a conflict copy, so no password is lost. An edit beats a delete.
Only devices whose collections include vault hold its key. An account created by a browser extension has no vault collection until a device with the words adds one with an Epoch entry.
9. Live updates (MQTT)
Live updates are only a doorbell. A notice tells a device to sync; it carries nothing to trust.
- A member device gets a token from
/v1/push-token:{"URL":"wss://mqtt.ferrykey.com/","Token":"…","Filter":"fk/<topic>/+","Expires":unix seconds}. Tokens last 30 minutes. - Connect with MQTT 3.1.1 (MQTT 5 also works) over a secure WebSocket to that URL, with the WebSocket subprotocol
mqtt. Send the token as the MQTT user name. The password is ignored. Use a clean session and no will (connections with a will are refused). Keep-alive is at most 300 seconds (0 is raised to 300). Packets are at most 4096 bytes. - Subscribe at QoS 0 to the filter, or to
fk/<topic>/<collection>. Nothing else is allowed, and clients may never publish. - Fetch a new token before
Expiresand reconnect. The token is checked again on every delivery, so an expired connection simply stops receiving.
Messages are retained (the latest per topic, kept in memory only), on topic fk/<topic>/<collection>, with payload {"c":"bookmarks","s":42}: the collection and its new commit number. Collection log means the membership log changed (for example a lock-out); s is then the log length.
What a message reveals: that a collection of one account changed, and its new number. The topic ID is a keyed hash of the account ID made with a server secret, so topics can’t be linked to accounts by others. Tokens are bearer tokens: treat them as secrets until they expire.
Push can be missed (restarts, sleeping devices). Clients must also poll.
10. Writing your own client
You may use your own software to sync your own account, for personal use, under the same terms and limits as our apps. We don’t offer support for it, and you’re responsible for keeping your keys and data safe in it. Protocol changes are handled as described in Versions and support.
Musts
- Do every check in What a client must check. Skipping them gives a malicious server back the powers this design takes away.
- Never send the words, the AMK, collection keys or any private key anywhere. Only public keys, signatures and envelopes go to the server.
- Forget the words once a device is set up. Store device keys in the operating system’s key store, not in a synced folder.
- Use a fresh random salt for every envelope and a fresh nonce for every request. Re-sign retries.
- Seal every change at the seq and epoch you actually commit at, and only produce valid documents. Other devices refuse invalid commits, and that stops them syncing.
- Send
X-Fk-Protocol: 2on every call and handleupgrade_requiredby stopping and telling the user. - Keep test vectors passing (see the test vectors) before pointing anything at a real account. Test against an account you made for the purpose.
Be nice
- Rely on live updates. Poll no more than every 5 minutes.
- Debounce local edits instead of committing every keystroke.
- On network errors, HTTP 5xx and
busy, back off: our browser extensions wait 15 seconds, doubling up to 5 minutes. - Upload a snapshot about every 32 commits, not more often.
- Create accounts only when a person asks for one. Signups need a proof of work and are limited per network.
Accounts unused by any device for 12 months are deleted. There is no email to warn you, so use your account now and then.
Changes
| Date | Change |
|---|---|
| 18 October 2026 | Lock-out seal: the remover snapshots every collection the removed device could write right after the Remove (the server now takes current-epoch snapshots while a rotation is pending), and clients refuse a removed device’s data that no seal or rotation snapshot vouches for. Closes the window between a removal and its rotation. A lock-out without a seal (older apps) is sealed by the locking-out device once it updates. No wire format change; no new version. |
| 17 October 2026 | This specification published. |
| 16 October 2026 | Additive: /v1/log responses gained Seen (when each device was last active, to the hour). No new version. |
| 14 October 2026 | Protocol 2: version 2 heads, signed snapshot statements, skipped heads in pulls, and the X-Fk-Protocol header. Protocol 1 retired the same day under the security exception (log rollback, old-key data and dropped commits). |