From 3fa210fc6003ad3736a40f1b57e1bb39f136211a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Xos=C3=A9?= Date: Sun, 25 Oct 2026 09:05:38 +0100 Subject: [PATCH] Add spec.md: goal, limits and rules for working on the project Co-Authored-By: Claude Opus 5.5 --- spec.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 spec.md diff --git a/spec.md b/spec.md new file mode 100644 index 0000000..fffa605 --- /dev/null +++ b/spec.md @@ -0,0 +1,41 @@ +# tlskit — spec + +The short contract for working on the shared HTTP/TLS client. `README.md` explains its use; this file says +what it promises to the apps that copy it. + +## Goal + +Let Android 2.2/2.3 apps reach modern `https://` servers (TLS 1.2, today's roots, SNI), which the +system's own TLS 1.0 stack can't. + +## Users + +Copied into: Plexamp Lite, Podlite, Noticias Lite, Calendar Lite (by hand, under +`android/org/gingercal/net`), AcasaLite, Tenda Lite and WikipeLite. The apps carry copies, not a dependency. + +## What it provides + +- `net/Http.java`: HTTP/1.1 on Bouncy Castle TLS 1.2 (renamed `com.minamp.bc`), keep-alive pooling, session + resumption, chunked bodies. +- `net/CertVerifier.java`: host name, validity dates, chain up to a bundled Mozilla root (trust anchors must + be CAs); optionally one pinned leaf certificate (SHA-256), with the fingerprint shown to the user. Untrusted + errors carry the chain. +- `net/AssetRoots.java` + `roots/`: Mozilla's roots as `assets/roots/-.der`; loaded roots + are kept in memory and a failed read is retried. +- `net/Threads.java`: threads with a 256 KB stack; network work must run on one. +- `net/DiagLog.java`: connection log with tokens removed from URLs. + +## Must not break + +- Must run on Dalvik for API 8: no newer Java or Android APIs. +- Must not clash with the old Bouncy Castle inside Android (keep the `com.minamp.bc` rename). +- Never log tokens or passwords. +- A change here is not done until it has been reinstalled into every app above and each one rebuilt + (and released through Tenda). + +## Workflow + +- `./install.sh ` copies `net/` into the app's package and `roots/` into its `assets/`. +- Bouncy Castle sources come from Plexamp Lite's `tools/setup_toolchain.sh` (`~/android-toolchain/bcsrc`); + roots are regenerated with Plexamp Lite's `tools/make_roots.py`. +- Test: `test/KitTest.java` on a desktop JVM against real FreshRSS, Nextcloud and Audiobookshelf servers.