Files
ts3java/ts3-client/docs/myteamspeak/IMPLEMENTATION.md
T
erikbrockoandClaude Opus 5.5 756e3850a3 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>
2026-10-15 12:37:50 +00:00

5.6 KiB

myTeamSpeak in the client

What is implemented, and what two-way sync would still need.

Sign-in and read-only import (done)

core/src/main/java/eu/lixko/ts3j/client/myts/ — pure Java, no Swing/Android dependency, and no JDK API that Android 13 lacks (hence HttpURLConnection, not java.net.http).

  • MyTeamSpeakLogin — the account the client stays signed in to. Like the official client's Account_Data (which stores email, the login token in its password field, and the account key as encryption_password), it keeps MyTeamSpeak.Credentials — email, login token, account key — in the 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. 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); 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.
  • Decrypted items are plain Item_Data, decoded by teamspeak/SyncItemDecoder. TeamSpeakImporter gains importSelected(all, chosen) (chosen bookmarks bring the identities they use) and isPresent(item); the policy is the local settings.db import's: additive and idempotent.

Frontends: Swing Options → "myTeamSpeak" tab (MyTeamSpeakPanel); Android Settings → Account → myTeamSpeak (ui/MyTeamSpeakScreen.kt). Both: sign in/out, the account's bookmarks and identities with a checkbox each and whether they are imported already, Refresh, "Import selected".

Observed on the live account: a bookmark may name its identity by the identity's name ("Default") instead 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

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 rate-limits abuse.