calendar-lite/README.md

Calendar Lite — Nextcloud CalDAV for Android 2.3 (Galaxy Mini)

A small native calendar client for Gingerbread (API 9/10). Built for a Samsung Galaxy Mini (GT-S5570, 240×320, Android 2.3.5) talking to Nextcloud at its normal https:// address.

Since 1.4 it brings its own TLS 1.2 (Bouncy Castle, the same client as Plexamp Lite, with Mozilla's root certificates and keep-alive connections), like the iPod version does with BearSSL. Put the normal https:// Nextcloud address in Settings, at home or away: no bridge is needed. The bridge sections below are kept for reference; a bridge address (pinned certificate) still works.

What it does

• Month view: a 6-week grid with a coloured mark per event (calendar colour), today outlined, the selected day's events listed below. Swipe or tap the arrows to change month; tap the month name for today; long-press a day to create an event on it. Months outside the synced window are fetched from the server when you open them
• Agenda view: upcoming events grouped by day (Menu > View switches; the choice is remembered)
• Interface in Galician (default) or English: Settings > Lingua / Language. Month and weekday names are built in, since Android 2.3 has no Galician locale data; in Galician weeks start on Monday. The system date/time pickers follow the phone's own language
• Offline cache (SQLite) of the last 35 days and the next 60 (Settings: "Days ahead")
• Create, edit and delete events (title, all-day, start/end, location, notes, alarm)
• Repeating events are shown correctly (server-side expansion, with a client-side fallback); they can be deleted on the phone but edited only in Nextcloud
• Pick which calendars to show and which one new events go to
• Background sync every 1–24 h, plus phone notifications N minutes before timed events
• Its own TLS 1.2 stack: connects to modern https:// servers directly
• Certificate pinning, so a self-signed server (or the old legacy-TLS bridge) is still safe against interception

It does not feed the stock Samsung calendar: 2.3 has no public calendar-provider API for that.

Why HTTPS broke on 2.3, and the old fix (not needed since 1.4)

Three separate problems, all fatal for a normal Pangolin/Traefik URL:

Problem	Gingerbread	Pangolin (Traefik)
TLS version	TLS 1.0 max	TLS 1.2 minimum
Root CA	no ISRG Root X1 (Let's Encrypt)	Let's Encrypt certificates
SNI	unreliable in Apache HttpClient	routes HTTPS by SNI

Lowering Traefik's TLS settings would weaken every site you host and still leave the CA problem. Instead, put a tiny legacy-TLS bridge next to Nextcloud and expose it with a Pangolin raw TCP resource (port-based, so no SNI needed). The bridge speaks TLS 1.0 with a self-signed certificate that the app pins by fingerprint, and forwards only /remote.php/dav/ to Nextcloud.

Galaxy Mini --TLS 1.0, pinned cert--> Pangolin VPS :8443 (raw TCP, WireGuard tunnel)
     --> newt --> caldav-bridge (nginx) --HTTP--> Nextcloud (CalDAV only)

Option A: bridge through Pangolin (works anywhere)

1. Bridge (on the Nextcloud host, in bridge/):
   • Edit nginx.conf: the server nextcloud:80; upstream and set $nc_host (a name in Nextcloud's trusted_domains). If Nextcloud forces HTTPS, also switch to proxy_pass https:// (see "Forced HTTPS / HSTS" below).
   • Edit docker-compose.yml: the Docker network your Nextcloud container is on.
   • ./make-cert.sh creates the certificate and prints its SHA-256 fingerprint. Note it.
   • docker compose up -d
2. Pangolin server (VPS):
   • config/config.yml: flags: allow_raw_resources: true
   • docker-compose.yml, gerbil service: add port 8443:8443
   • config/traefik/traefik_config.yml, entryPoints: add tcp-8443: { address: ":8443/tcp" } (the tcp-<port> name is required)
   • Open TCP 8443 in the VPS firewall, then docker compose down && docker compose up -d
3. Pangolin dashboard: Resources, Add Resource, Raw TCP/UDP, TCP, public port 8443, target = the bridge as seen from your newt site (caldav-bridge:8443 if newt shares its Docker network, otherwise 127.0.0.1:8443 with the port published). Leave Proxy Protocol off.
4. Phone: server address https://<your-pangolin-domain-or-IP>:8443. On the first test the app shows the certificate fingerprint; tap Trust only if it matches step 1.

Pangolin's SSO does not apply to raw TCP resources; protection here is Nextcloud's login (use an app password) plus the pinned certificate. The web UI isn't reachable through the bridge.

Optional, to let Nextcloud's brute-force protection see real client IPs: tick Enable Proxy Protocol on the resource, add the pp-transport-v1/v2 block to Pangolin's dynamic_config.yml (see the Pangolin raw-resources docs), and in nginx.conf use listen 8443 ssl proxy_protocol;, set_real_ip_from <newt address>;, real_ip_header proxy_protocol;. Enable both sides together or every connection fails.

Option C: Nginx Proxy Manager with port forwarding (no Pangolin)

If your router already forwards 80/443 to Nginx Proxy Manager, the legacy endpoint can live in NPM itself on its own port. NPM's normal sites on 443 keep their modern TLS settings.

1. ./bridge/make-cert.sh nxc.anosanube.ovh <npm>/data/legacy-caldav, and note the fingerprint.
2. Copy bridge/npm/http.conf to <npm>/data/nginx/custom/http.conf; if that file already exists, append the block to it. NPM includes it at the end of its http block.
3. In NPM's docker-compose.yml add - '8443:8443' under ports, then docker compose up -d.
4. Forward TCP 8443 on the router to the NPM host.
5. Phone: https://nxc.anosanube.ovh:8443, then tap Trust if the fingerprint matches.

It forwards to NPM's own nxc.anosanube.ovh proxy host over loopback HTTPS, so Nextcloud's backend address, HSTS and forced HTTPS need no extra handling. Check from a PC with openssl s_client -connect nxc.anosanube.ovh:8443 -tls1 -cipher 'AES128-SHA:@SECLEVEL=0'. At home, the phone needs your router to support NAT loopback (it already does if https://nxc.anosanube.ovh works from your Wi-Fi).

Option B: home Wi-Fi only (no Pangolin)

Use http://<nextcloud-LAN-IP> as the server address. Nothing to set up, but it syncs only at home and the password crosses your LAN unencrypted. The app warns if http:// points at a non-LAN address.

Avoid a plain-HTTP Pangolin resource: it would send your password in clear over the internet.

Forced HTTPS / HSTS

HSTS itself doesn't matter to the app. Strict-Transport-Security is enforced by browsers; the app's HTTP client ignores it, and a Pangolin raw TCP resource passes bytes through without adding headers. The bridge strips the header anyway, so a modern browser that you point at the bridge (e.g. while debugging) doesn't lock itself to the self-signed certificate.

What does matter is a Nextcloud that redirects plain HTTP to its public https:// URL (web server rule, overwriteprotocol, overwrite.cli.url). Symptoms in the app:

App says	Cause	Fix
"Redirect loop … switch the bridge to proxy_pass https://"	bridge talks HTTP to a Nextcloud that redirects HTTP→HTTPS	in nginx.conf: server nextcloud:443; and proxy_pass https://nextcloud;
"The server redirected http:// to https://… (forces HTTPS / HSTS)"	Option B: phone talks http:// to that Nextcloud on the LAN	use the bridge address, or let the LAN vhost serve /remote.php/dav/ without the redirect
"The server redirected to https://cloud…, not the address set in the app"	an absolute redirect wasn't rewritten	keep the proxy_redirect and absolute_redirect off lines in nginx.conf

With proxy_pass https:// only the bridge-to-Nextcloud hop uses HTTPS (modern TLS, any certificate, since it's your own server). The phone side stays TLS 1.0 with the pinned certificate. If the bridge can't reach Nextcloud directly, proxy_pass can also point at the public Pangolin URL. In that case Pangolin authentication must let /remote.php/dav/ through, and you should turn proxy_ssl_verify on.

Install on the phone

1. Settings, Applications, tick Unknown sources.
2. Copy CalendarLite.apk to the SD card (USB) and open it with the file manager, or download it over plain http:// (the 2.3 browser can't open most HTTPS sites either).
3. Open Calendar Lite, Menu, Settings. In Nextcloud create an app password: Settings, Security, Devices & sessions. Fill in server, user, app password, then Save and test connection.

Menu key: View (Month/Agenda), New event, Sync, Today, Calendars, Settings. Tap an event for details, Edit and Delete.

If installation fails, check the file arrived whole (about 1 MB; some browsers save a truncated or renamed .apk.zip) and that there are a few MB free on the internal storage. On a PC with adb, adb install CalendarLite.apk prints the exact reason (INSTALL_FAILED_...).

Building

Needs JDK 11+, Python 3, d8 and apksigner.jar (Android SDK build-tools), apktool.jar (2.9+, which bundles Google's aapt and smali), and the Bouncy Castle sources renamed to com.minamp.bc that Plexamp Lite's tools/setup_toolchain.sh prepares (BC_SRC, default ~/android-toolchain/bcsrc). No Gradle.

D8=d8 APKTOOL=~/apktool.jar APKSIGNER=$SDK/build-tools/34.0.0/lib/apksigner.jar ./build.sh
# add ANDROID_JAR=$SDK/platforms/android-10/android.jar to compile against the real platform

Pipeline: javac → d8 → baksmali/smali (clean dex 035) → aapt v1 for manifest and resources → apksigner v1 signature → zipalign. The script ends by running apksigner verify for API 8–10 and checking the dex header, and fails rather than produce an APK that 2.3 would reject.

Don't sign with jarsigner: modern versions add PKCS#7 signed attributes, which Android only accepts from 4.4, so the phone refuses to install it. That was the bug in the first build. gingercal.keystore (password android) is the signing key; keep using it so updates install over the existing app.

Tests (desktop JVM, need a CalDAV server such as Radicale on :5232 with user xose/secret):

javac -d out src/org/gingercal/*.java $(ls test/org/gingercal/*.java | grep -v NetTest)
java -cp out org.gingercal.CoreTest          # discovery, sync, recurrence, create/edit/delete
java -cp out org.gingercal.RedirectTest      # redirect handling (no server needed)
# the bundled TLS transport (needs the android.jar and Bouncy Castle sources to compile):
#   java -cp out org.gingercal.NetTest assets/roots http://127.0.0.1:5232 xose secret
java -cp out org.gingercal.I18nTest          # Galician dates, titles and messages

tools/check_i18n.py (run by the build) fails if any interface text lacks a Galician translation or the placeholders differ. tools/check_api.py verifies every framework call in the dex against published Android API declarations.

Layout

• src/ CalDAV core, platform-neutral: discovery, PROPFIND/REPORT, iCalendar, sync, pinning
• android/ activities, sync service, alarms, SQLite cache, NetHttp transport
• android/org/gingercal/net/ the bundled TLS 1.2 HTTP client from Plexamp Lite; assets/roots/ Mozilla roots
• stubs/ compile-only Android API 10 signatures (never packaged)
• bridge/ legacy-TLS endpoint: standalone nginx (config, compose file), npm/http.conf for Nginx Proxy Manager, certificate script
• res/ app name, launcher icon (ldpi to xhdpi; master in art/) and stat_notify, the white status-bar icon for reminders
• tools/ dex disassembler helper, zipalign, dex/API checkers, d8 workaround

Security notes

With the bundled TLS 1.2 the connection to Nextcloud is checked like a browser would: host name, dates, and a chain up to a Mozilla root. The notes below are about the old bridge.

TLS 1.0 with AES-CBC is old but, combined with a pinned certificate, still keeps the connection private and authenticated against anyone without the bridge's private key. The bridge exposes only the DAV endpoint. Use an app password so you can revoke the phone from Nextcloud. If the phone ever reports that the certificate changed and you didn't regenerate it, don't trust it.