Files
ts3java/ts3-client/docs/myteamspeak/IMPLEMENTATION.md
T
erikbrockoandClaude Opus 5.5 78fc45f9b2 Rename to TeamSpook TS3j, package eu.lixko.ts3j.client
Java/Kotlin sources move from com.ts3client to eu.lixko.ts3j.client, and
the Android application id becomes eu.lixko.ts3j.client. The product name
shows as "TeamSpook TS3j" in window titles, the tray, the launcher entries,
notifications and PipeWire streams.

The desktop profile directory, WM_CLASS and ts3j.* system properties keep
their names so existing settings and launchers carry on working.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 14:43:34 +00:00

49 lines
3.2 KiB
Markdown

# 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.
- `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.
- `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 (not done)
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.
## Etiquette
One sign-in is three requests. Don't loop sign-ins while testing; the service sits behind Cloudflare and
rate-limits abuse.