Phase 1: talk to a server and sign in

[AndyScherzinger]

Summary

Phase 1: the app can talk to a server. A person types a server, the app finds its Mastodon API, whether Nextcloud Social sits at the domain root with the rewrite rules or under its app path without them, and signs in with OAuth (PKCE S256, verified App Link with a custom-scheme fallback). The account is stored with its token in a Keystore-backed vault, and the app learns what the server can do.

• core:model: the domain model, with ContentClassifier, CharacterCount, TimelineKey and ServerCapabilities.
• core:network: a plain OkHttp + kotlinx.serialization client with no Retrofit, because every account has its own base.
  • Internal wire DTOs map to domain types, and decoding is lenient and lossy.
  • A Link cursor is followed only on the API base's origin, and dot segments in paths are refused.
  • A read answered 429 with a short Retry-After is retried once.
  • User-trusted certificates are kept per host, and KeyChain client certificates are supported.
• Server discovery:
  • The RFC 8414 issuer, the domain root, the app path, the pretty app path and a typed path are raced, and the lowest rank that answers wins.
  • NodeInfo serves as the cross-check of the software.
  • A base that stopped answering is re-probed at most hourly.
• OAuth and capabilities:
  • The app registers once per server.
  • The sign-in in flight is kept in the vault, so it survives process death and never reaches a Bundle.
  • OAuth requests never follow a redirect, and a callback's state is checked before anything else in it.
  • A new account that verify_credentials cannot describe yet falls back to /oauth/userinfo.
  • Capability detection covers the Nextcloud Social extensions, Pixelfed features and the Nextcloud theme.
• Storage: accounts.db (Room, schemas exported) plus an AES-GCM token vault with an AndroidKeyStore key, StrongBox where the device has it. A lost vault marks accounts needsReauth, and a 401 does the same; nothing is ever deleted.
• core:testing:
  • The fixture corpus from the dev instance, plus mastodon.social discovery captures.
  • A mock server in seven shapes: with and without the rewrite rules, connected, Mastodon, core-only, rate-limited, and malformed entities.
• feature:signin:
  • Screens for the terms gate, server entry, probing, the server card, the browser wait, failures and an untrusted certificate.
  • A failure lists what was tried, offers a hand-typed API address, and copies a note for the administrator. The note links Nextcloud Social's contrib/webserver rules instead of embedding them, because those files are AGPL-3.0-or-later.
  • A client-certificate picker sits under Advanced.
  • A release build refuses http:// with a message that says why (https is required), not as an address it can't read.
  • A server nobody answers for (a typo, a server that is down, no network) says it could not be reached, without the note for the administrator, which is kept for servers that answer but serve no Mastodon API.
  • The server card trims the server's texts; mastodon.social ends its description with blank lines.
• Shorts tab: selection now shows in the icon's shape as on the other tabs (the Slideshow glyph looked the same filled and outlined). This is its own commit because the icon came from the design-system commit on main; a screenshot with Shorts selected guards it.
• Emulator smoke (ui.yml): it had never completed, so it gets its own commit, separate from the phase's code. The job frees disk space so the emulator can start at all, builds the benchmark APKs before the emulator runs, and keeps a screenshot and view dump when a flow fails.
• Build: every module's unit and screenshot tests now run in CI through the alohaUnitTests and alohaScreenshotTests aggregates. Before this, CI ran only the app module's flavoured tasks, so the library tests never ran there.

Exported component: OAuthRedirectActivity is exported with an autoVerify App Link filter, because the browser must be able to deliver the OAuth callback. It draws nothing, hands the URI to an in-process inbox and finishes. It has taskAffinity="", so no callback URI travels in an Intent to the main activity.

New dependencies, each with SHA-256 and PGP entries in gradle/verification-metadata.xml:

Dependency	Scope
OkHttp 5.5.0	runtime
mockwebserver3 and okhttp-tls	test
Room 2.8.5 and its Gradle plugin	runtime, build
DataStore 1.2.1	runtime
androidx.browser 1.10.0 (Custom Tabs)	runtime
kotlinx-coroutines-test, Turbine, androidx.test core and the JUnit vintage engine	test

No new permission.

APK size: the release APK grows from 1.11 MB to 1.99 MB. R8 and resource shrinking are on, and no keep rule is wider than the Navigation keys' serializers. The growth is real code, mostly the model, the networking and serialization, Room and DataStore; OkHttp's public-suffix list alone is 130 KB. config/size-baseline.json moves to the new size in the sign-in commit, where the growth enters the app.

Docs: the "On Android" part of docs/02-server-api.md now covers the client, errors, rate limiting and TLS, how the API base is found, the sign-in rules and the Android differences in capability detection. Each part is in the commit that brought in the behaviour it describes.

Size: about 18.5k lines of Kotlin and XML, far above the thousand-line guideline, plus about 22k lines of fixtures. The phase is one vertical slice whose acceptance is sign-in end to end, so it is split into nine commits that each build on their own and can be reviewed one at a time.

Deferred:

• OAuthClient.revoke is implemented and tested but unused until a sign-out control exists.
• The server card's thumbnail waits for the image loader of Phase 2. Nextcloud's thumbnail is also an SVG, which remote content may not use.

Test plan

• alohaUnitTests is green across all modules, including:
  • sign-in against all seven mock configurations;
  • decoding of every api/ and writes/ fixture through its endpoint factory, with nothing dropped, and a check that fails when a new fixture is left unmapped;
  • ServerFactsTest, which pins the server behaviours the client relies on;
  • account recovery after a lost vault and after a 401;
  • secret redaction in logs and toString.
• alohaScreenshotTests is green: every sign-in step in light, dark, tablet, 200 % font and right to left.
• detekt ktlintCheck lint alohaArchitectureCheck is green, and assemble passes for both flavours plus :benchmark:assemble.
• The build passes with strict dependency verification.
• Manual run against the WSL dev instance (Nextcloud Social 0.26.97, http://nextcloud.local), through the opt-in LiveInstanceTest. Set ALOHA_LIVE_SERVER, ALOHA_LIVE_USER and ALOHA_LIVE_PASSWORD, then run ./gradlew :core:testing:testDebugUnitTest --tests '*LiveInstanceTest*'.
  • Sign-in succeeds with the root rewrite rules off and with them on, and the API base is found at /index.php/apps/social/.
  • Capabilities are complete (Nextcloud Social, filters v2, stories, collections), and the theme reads #00679e.
  • Exchanging with a wrong verifier gets 401 invalid code_verifier.
  • Plain PKCE gets 400 unsupported code_challenge_method.
  • A made-up token gets 401, which the client maps to Unauthorised.
• On an emulator (Pixel 10 Pro AVD, Android 37, Play Store image, debug build) against the same instance, reached through a host-side HTTP proxy because Android resolves .local only over multicast DNS:
  • The terms gate, server entry, probe and server card work. The Custom Tab opens Nextcloud's login, then the consent page naming Aloha Social, and the code goes to the custom scheme, since the App Link cannot verify until aloha.social publishes its asset links.
  • The callback reaches OAuthRedirectActivity, which hands it to the app in the same task and leaves no activity behind. One token exchange runs, capabilities are detected, and the shell opens.
  • The app process was killed while the consent page was open; authorising then cold-started the app, which read the attempt back from the vault and finished the sign-in.
  • A cold relaunch stays signed in (the token decrypts from the Keystore after a restart).
  • No code, verifier, token or client secret appears in logcat. The authorize URL (state and PKCE challenge) is logged once by the system launcher's TopTaskTracker at debug level, outside the app's control.
  • Sign-in against mastodon.social also works (manual, emulator, a real account). The account is stored with Mastodon 4.8.0 capabilities: API version 11, grouped notifications, filters v2, translation. The Nextcloud extensions are off.
• The emulator smoke workflow (ui.yml) passes on this branch (run 36592272873): the Maestro flow on the release builds of both flavours, then the startup macrobenchmark. The flow used to expect the home screen at launch, which this PR moves behind sign-in. It now covers terms, then sign-in, and checks that the terms stay accepted after a restart. It waits out the "System UI isn't responding" dialog that a freshly booted CI emulator shows over the app.

Checklist

• One concern; split if it approaches a thousand changed lines
• Tests for every non-trivial branch; fixtures from the dev instance where the server is involved
• detekt ktlintCheck lint alohaArchitectureCheck green, no baseline grown
• Screenshots re-recorded only where the UI change is intended
• Accessibility: labels, 48 dp targets, headings and paneTitle on new screens, 200 % font preview
• Strings in strings.xml with translator comments
• No new exported component, permission or dependency without a line here explaining it
• docs/ updated where behaviour changed
• AI tools were used for this contribution (commits carry Assisted-by:)

[github-actions]

Debug APK (generic flavor) for 9862439: https://github.com/AlohaSocial/Android/actions/runs/36604324266/artifacts/11050179993 — kept for 5 days.