myTeamSpeak: two-way sync of bookmarks and identities

MyTeamSpeakSync compares each item against what the last run left: a
change on one side goes to the other, deletions too, and an item changed
on both sides is a conflict for the user. The first run pairs items up by
identity key or bookmark name and address. Edits are written over the
item's Item_Data field by field, so what we do not model survives.

The protocol was probed live and checked against the official client:
the server stores whatever revisions it is sent and never reports a
collision, so the client re-reads the cursors before writing. Edits carry
last_known_version like the official client's, which applies them within
its one-minute poll. All requests now share one session; signing in for
each got the account's logins throttled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-15 12:37:50 +00:00
co-authored by Claude Opus 5.5
parent ab6bf30003
commit 756e3850a3
19 changed files with 1910 additions and 156 deletions
+37 -8
View File
@@ -13,11 +13,14 @@ that Android 13 lacks (hence `HttpURLConnection`, not `java.net.http`).
private profile file `myteamspeak.properties`; never the password. `signIn` derives them, reads the
account and only then saves them; `fetch` reads the account again with the saved ones; `signOut`
deletes the file. When the server rejects saved credentials (`ERROR_LOGIN_FAILED`, e.g. the password
was changed elsewhere) `fetch` signs out.
was changed elsewhere) `fetch` signs out. All requests share one session (`MyTeamSpeakLogin.request`),
as the official client's do: signed in on first use, again when the service reports it expired
(102/109), ended on sign-out or exit. Signing in for every request gets the account's logins throttled
within a few dozen (seen 2026-10-15: `login` timed out for minutes).
- `MyTeamSpeak.download(Credentials)` — signs in (`authentication/login`), unwraps the item key, pulls
BOOKMARK, IDENTITY and ITEM_FOLDER with one `synchronization/requestServerItems` against an empty
local state (all-zero global and class versions, no details), decrypts every item, then ends the
session (`authentication/deleteSession`). Each read signs in afresh; no server session is kept.
session (`authentication/deleteSession`); `MyTeamSpeakLogin` does the same in its shared session.
- `MyTsCrypto` — PBKDF2-HMAC-SHA512 login token and account key, `LoginSession.key` unwrap (AES-256-GCM),
item frame decryption (little-endian AES-CTR + SHA-512 trailer). See `CRYPTO_RE_SALT.md`.
- `MyTsTransport` — the `application/ts3cloud` framing over HTTP/1.1; an interface so tests replay a server.
@@ -35,13 +38,39 @@ of its item UUID; the importer resolves both.
Tests: `MyTsCryptoTest` (captured vectors), `MyTeamSpeakTest` (download against a replayed server built from
the captured login and item), `MyTeamSpeakLoginTest` (persistence, failed sign-in, rejected credentials).
## Two-way sync (not done)
## Two-way sync
Would additionally need the server's global and per-class version cursors and each item's
`item_uuid`/`sync_version_uuid` persisted, and a mapping between our bookmarks/identities and those items. The request/reply state machine,
mutation table, and item encryption (`IV || CTR || SHA-512`, random IV) are in `CRYPTO_RE_SALT.md` section 5. Open points: when edits rotate `sync_version_uuid`, the role of
`last_known_version`, the collision merge policy, and confirming the deletion tombstone before anything
destructive is sent.
`MyTeamSpeakSync` (with `SyncKind`, `SyncFields`, `SyncState`): bookmarks and identities, run by hand
(Swing: Options → myTeamSpeak → Synchronize; conflicts in `SyncConflictsDialog`). A run is
`fetch` (network) → `plan` (stores' thread) → user settles `Plan.conflicts()` → `upload` (network) → `apply`
(stores' thread). Nothing changes on either side before `upload`, and here only after it succeeded.
The comparison is three-way per item, against `SyncState` (profile file `myteamspeak-sync.properties`: the
global cursor, each class's cursor, and per item its server revision, plaintext `Item_Data` and local id).
Changed on one side → carried over (deletions too); on both → a `Conflict` with a field-by-field diff;
first run → items paired by identity UID or bookmark name+address, the rest carried over. Edits are
written over the item's current `Item_Data` field by field (`ProtobufMessage`), so fields this client does not
model survive.
### How the service and the official client behave (live, 2026-10-15)
Probed against the test account and by capturing the official 3.6.2 client's traffic.
- `requestServerItems`: a class whose cursor matches comes back empty; any other comes back whole. Item
details in the request are ignored; there are no deltas. Deleted items simply vanish.
- `synchronizeItems` stores what it is sent: the class revision (client-made, a fresh UUID), each item's
wire revision and blob; replies `300` and a new global cursor. It never reports `COLLISION`, whatever is
stale — conflicts are the client's to find. `push` therefore re-reads the cursors first and fails with
`changedMeanwhile` when any moved.
- The official client polls about once a minute with its cursors and the global cursor, and on startup with
random class cursors (a full read). It applies what it reads live; it writes `settings.db` only later, so
read its state from the UI, not the database, while it runs. Our pushes do not reach its push channel.
- Its change upload: plaintext `sync_version_uuid` new, `last_known_version` := the previous one,
`manipulated` = 3; a fresh wire revision; only the changed items; the global cursor echoed. Adds carry
`manipulated` = 0. Deletion: the detail's `item_delte_on_server` = 1 under a fresh revision (it also
sends the last blob; one without is accepted too). We write the same.
- It reports "myTeamSpeak account collision detected" and stops applying when a remote change meets an item
it still holds as locally changed. Seen once, after mixed probing; not with the writes above.
## Etiquette
One sign-in is three requests. Don't loop sign-ins while testing; the service sits behind Cloudflare and
+2 -6
View File
@@ -84,9 +84,5 @@ Recovered constructions:
## Remaining reverse-engineering gaps
Password login, key unwrap, item encryption/integrity framing, two-phase comparison, and the local
manipulation flags are recovered. The remaining uncertainties are narrower: where ordinary edits rotate
`sync_version_uuid`, the exact lifecycle of `last_known_version`, the official collision winner/merge
policy, and instruction-level confirmation of the deletion-detail builder. Recovery-key import is also
not yet recovered. The read-only pull is implemented in `eu.lixko.ts3j.client.myts` (see IMPLEMENTATION.md); destructive upload
should remain gated until the deletion mapping has a fixture or controlled integration test.
The synchronisation protocol is settled by live probing and capture; see IMPLEMENTATION.md "How the
service and the official client behave". Recovery-key import is not recovered.