Libellus Potionis

The project uses Git, the most widely used distributed version control system, hosted on GitLab. Repository: gitlab.com/godisch/potillus

Small tasks for new or casual contributors are identified in the issue tracker with the "good first issue" label and described in CONTRIBUTING.md ("Good first issues"), which highlights native-speaker translation review of the machine-generated locales, documentation, and test cases as good entry points.

Write (push) access to the canonical repository (hosted on GitLab) requires two-factor authentication as a documented project policy: docs/GOVERNANCE.md ("Repository access and account security") states that any account with write access MUST have cryptographic 2FA enabled. Currently the sole maintainer is the only account with write access and has 2FA enabled; the policy binds any future account granted write access. GitLab additionally accepts no account password for git over HTTP/S at all — an access token or an SSH key is required — so a stolen password alone cannot push. Per-project 2FA enforcement is a group-level setting the project's plan does not offer, so the requirement is enforced by written policy.

The project's 2FA policy (docs/GOVERNANCE.md, "Repository access and account security") mandates a cryptographic method — a TOTP authenticator app or a hardware security key — and explicitly excludes SMS. The maintainer's GitLab 2FA uses such a cryptographic method.

CONTRIBUTING.md ("Code review requirements", Section 2) documents the project's code review process: how review is conducted (every change is reviewed before merge by the maintainer as reviewer and sole merger; the reviewer runs the build, the test suite, and tools/release-check.sh locally; the GitLab CI pipeline covers only the device-free static checks, see .gitlab-ci.yml), an explicit checklist of what must be checked (scope/privacy fit, architecture rules, coding and KDoc conventions, warnings-as-errors, mandatory tests, localization completeness, per-file licensing, DCO sign-off, and schema-freeze rules), and the acceptance criteria required for a change to be merged.

The Android build is reproducible. F-Droid builds the app from source and verifies that the result is bit-for-bit identical to the maintainer-signed APK before publishing it (F-Droid's Reproducible Builds process). This is documented in SECURITY.md ("Verifying releases"), and the F-Droid build recipe (in fdroiddata) pins the build and the allowed APK signing key, so anyone can rebuild from a release tag and compare against the published APK. This reproducibility guarantee applies to the productive distribution channels: the GitLab release tags and F-Droid, both of which carry the maintainer's own signature and can be rebuilt and compared bit-for-bit from source. The planned store channels differ and are not author-reproducible in the same sense: Google Play re-signs the upload with a Google-held app-signing key, and the Apple App Store re-signs the submission with an Apple identity, so the published binary on those channels is signed by the store, not by the maintainer, and cannot be reproduced bit-for-bit by a third party. The iOS build is defined declaratively (XcodeGen project.yml, a pinned Swift package for the single dependency) and is verified reproducible: make release-ios archives twice on the pinned Xcode and stages only when the two unsigned Potillus.app payloads are byte-for-byte identical. App Store distribution still re-signs with an Apple identity, so — as on Google Play — the delivered binary is not third-party-reproducible; that is a platform property, not a build defect.

The test suite is invoked in the standard way for a Gradle/Android project: ./gradlew test runs the JVM unit tests and ./gradlew connectedCheck runs the instrumented tests on a device or emulator. This conventional invocation is documented in CONTRIBUTING.md (Section 5, "Testing strategy", and the change-submission checklist in Section 2). The iOS tests are invoked the standard way too: swift test runs the PotillusKit unit tests, and the app-target tests run under xcodebuild. Both are wired into the Makefile's iOS targets.

A GitLab CI pipeline (.gitlab-ci.yml) runs on every merge request targeting main and executes the project's device-free gates — tools/release-check.sh --Werror, make check-static and an osv-scanner source scan — so contributed changes are checked continuously rather than only at release time. The checks are enforced: Merge requests > "Pipelines must succeed" is enabled, so a red pipeline blocks the merge. Observed green at https://gitlab.com/godisch/potillus/-/pipelines/2700494992. The heavier half — the unit-test and lint suites, which need an SDK-bearing image and, for iOS, macOS — still runs locally before each release; widening the pipeline to cover it is tracked in docs/ROADMAP.md and is what the related automated_integration_testing (silver) still waits on.

The JVM unit-test suite clears the 90% line floor with headroom, measured with Kover over the unit-testable code (make -C android cover-figures prints the current figure). Android-runtime-bound code (Compose UI, Room database/DAOs, DataStore preferences, Keystore, PDF/WebView rendering, and MediaStore import/export) is excluded from this figure and verified instead by the instrumented suite (src/androidTest). A build-breaking floor of 90% line and 80% branch coverage is enforced by the koverVerify Gradle task in the release gate (make cover-check). Methodology: CONTRIBUTING.md §5; scope/enforcement: app/build.gradle.kts. The iOS port's PotillusKit suite (ios/PotillusKit/Tests) clears the same 90% line floor, enforced by the same release gate (make cover-check, via swift test --enable-code-coverage and tools/check-ios-coverage.py), so both implementations meet this criterion.

Branch coverage (Kover, over the same unit-testable scope the statement-coverage criteria are answered on) clears the 80% threshold, and stays cleared because the threshold is enforced rather than observed; make -C android cover-figures prints the figure a given commit measures. No percentage is quoted here: the one that stood in this field until the 0.84.0 QA round had no run behind it. A build-breaking floor of BRANCH >= 80 is enforced by the koverVerify Gradle task, which release-android runs before it builds and the GitHub mirror's Android workflow runs on every push. The figure comes from ./gradlew :app:koverXmlReport; tools/release-check.sh --coverage prints it alongside the line figure. Scope and methodology: CONTRIBUTING.md §5; enforcement: app/build.gradle.kts. The iOS PotillusKit suite enforces a 90% LINE floor by the same release gate, but the swift test/llvm-cov path yields no branch data, so iOS branch coverage stays a tracked goal in docs/ROADMAP.md.

The application performs no network communication: it does not declare the INTERNET permission, works entirely offline, and transmits no data. There are therefore no network protocols whose security could be assessed.

The application does not use TLS because it performs no network communication at all (no INTERNET permission, offline-only). There is no TLS configuration or version to assess.

The criterion requires the repository and download sites to send four key hardening headers (CSP, HSTS, X-Content-Type-Options: nosniff, X-Frame-Options). Both sites send all four. The download site (F-Droid) does, and so does the repository host: GitLab serves gitlab.com/godisch/potillus with a Content-Security-Policy, HSTS, X-Content-Type-Options: nosniff and X-Frame-Options: SAMEORIGIN. (This criterion was unmet on the project's previous host, which sends neither CSP nor X-Content-Type-Options; the move to GitLab resolved it.)

A security review was performed in 2026 and is recorded in docs/ASSURANCE_CASE.md ("Security review record"). It takes into account the security requirements (SECURITY.md, "Security model") and the security boundary (the threat model and trust boundaries in the assurance case), combining that analysis with an Android-focused code/QA pass over the security-relevant areas (at-rest Keystore encryption, input and backup/import validation, CSV-injection neutralization, the permission surface and exported components, and the FLAG_SECURE / allowBackup / R8 hardening). No unresolved high-severity issues are known; residual risks are stated explicitly.

Release builds apply R8 code shrinking and obfuscation (isMinifyEnabled = true) with resource shrinking and the optimizing ProGuard configuration. The manifest sets android:allowBackup="false" to prevent backup-based data exfiltration, and the app applies WindowManager FLAG_SECURE by default from cold start to block screenshots, screen recording, and Recents-thumbnail exposure. The permission set is minimal (no network or telephony; only USE_BIOMETRIC) and only the launcher activity is exported. These complement the hardware-backed Keystore at-rest encryption and the warnings-as-errors/lint gate. The R8, resource-shrinking and lint configuration lives in android/app/build.gradle.kts. The iOS port applies the platform-equivalent hardening — the App Sandbox, no network entitlement, and the encryption key held in the iOS Keychain (SecretKeyProviding) — while iOS-specific items such as an explicit App Transport Security declaration are tracked in docs/ROADMAP.md.

No dedicated fuzzer or sanitizer is applied, but the criterion's allowance for an automated test suite with at least 80% branch coverage applies: branch coverage clears 80%, enforced as a build-breaking BRANCH >= 80 floor by koverVerify in the release path, so a drop below the threshold fails the build rather than going unnoticed; make -C android cover-figures prints the figure a given commit measures. The suite also runs against a real runtime rather than only on the JVM: the Android instrumentation tests in src/androidTest (Room migrations, Compose UI, on-device locale formatting, report export) execute on an emulator via the mirror's instrumentation workflow, which runs on every push that touches android/. Until the 0.84.0 QA round this answer read "branch coverage is not yet measured", which was never true — Kover measures branches, or it could not enforce a bound on them; only the figure went unprinted.

The domain and data layers carry run-time invariant assertions on both platforms, at the same sites: non-negative day counts and streaks in DayResolver, and non-negative grams/BAC plus the sliding-window invariant in AlcoholCalculator, written as Kotlin assert() on Android and Swift assert() on iOS. They are checked when the test suites run — Kotlin assertions are enabled under -ea, and Swift assertions are live in the debug configuration swift test builds — and compiled out of release builds, so they cost shipped users nothing.