Libellus Potionis

The project provides a clear, low-friction upgrade path to newer versions. The app is distributed via F-Droid (with Google Play planned), where users receive and install updates through the store's normal update mechanism, with no manual steps. User data is carried forward automatically across versions by versioned Room database migrations, which are covered by an instrumented MigrationTest, so upgrading never loses data. Because the upgrade path is straightforward, no separate upgrade documentation is required; as a mobile app, only the newest version is distributed, so maintaining older versions in parallel is unnecessary. On iOS the planned Apple App Store delivers updates through the same automatic store mechanism, and the shared JSON backup format carries user data forward across versions.

The project uses the GitLab issue tracker to track individual issues. The tracker is enabled and public, and users are directed to it: the README ("Feedback & Contributing") and CONTRIBUTING.md §2 point bug reports and enhancement suggestions there, while SECURITY.md routes security-sensitive reports to a private channel instead. Issue tracker: gitlab.com/godisch/potillus/-/issues

No externally reported security vulnerabilities have been resolved in the last 12 months, so there are no reporters to credit. Should this change, the project's practice is to credit reporters of resolved vulnerabilities unless they request anonymity; the reporting channel is documented in SECURITY.md.

The project has a documented vulnerability-response process in SECURITY.md. It specifies a private, PGP-encrypted reporting channel to android@godisch.de (with the maintainer's published PGP fingerprint obtained from the official Debian keyserver) kept separate from the public issue tracker, states what a report should include, commits to acknowledging reports within 14 days followed by assessment and response, and defines the scope of what qualifies as a security issue.

The project identifies a specific coding style guide for its primary language and requires general compliance. CONTRIBUTING.md §4 ("Coding conventions") directs contributors to follow the official Kotlin coding conventions (kotlinlang.org/docs/coding-conventions.html) and adds project-specific rules (mandatory KDoc on public API, constant placement, default-value consistency, enum persistence by name). Compliance is required through the review process (§2 makes the documented conventions a merge condition) and is partly enforced automatically via Kotlin's allWarningsAsErrors and Android Lint's warningsAsErrors gates. For Swift the project follows the community SwiftLint rule set (pinned to 0.65.0) enforced in --strict mode, the direct counterpart to the Kotlin conventions, plus the same review requirement.

The project automatically enforces its selected Kotlin coding style using ktlint (a FLOSS tool), integrated via the org.jlleitschuh.gradle.ktlint Gradle plugin. Style settings are defined in the repository-root .editorconfig (official Kotlin conventions). The ktlintCheck task runs as part of the standard check lifecycle and fails on violations, and ktlintFormat auto-formats sources; CONTRIBUTING.md §4 documents this for contributors. Enforcement is build-time only and not on the release-assembly path, so reproducible builds are preserved. On iOS enforcement is automated by SwiftLint --strict (pinned 0.65.0) as part of make ios, so a style violation fails the build rather than relying on review alone.

The project compiles no C/C++ sources on either platform: there is no externalNativeBuild, CMake or NDK configuration on Android, and the iOS app is pure Swift. The only .so references are in a jniLibs packaging block that excludes them from the APK. CFLAGS/CXXFLAGS-style variables therefore have nothing to apply to.

Neither platform compiles C/C++ sources: there is no NDK, CMake or externalNativeBuild configuration on Android, and the iOS app is pure Swift. Kotlin/JVM debugging metadata and the dSYM the Xcode build emits beside the iOS binary are both handled by the standard toolchains rather than by native compiler flags, so there is no flag-controlled native debugging information for this control to preserve or strip.

The project builds with Gradle, not make. Gradle constructs a single directed acyclic task graph for the whole project during configuration and resolves dependencies across the entire build, which is the non-recursive build model this criterion calls for; the pitfalls of recursive make do not apply. The build comprises a single application module (:app) declared in settings.gradle.kts, so there is no recursive subdirectory building. (Because the project does not use make, N/A would also be a defensible selection.) The iOS port likewise builds non-recursively: SwiftPM and xcodebuild resolve one package graph (ios/PotillusKit) rather than recursing through subdirectory makefiles.

The project has a reproducible build and this is verified externally: the app is built from source and distributed via F-Droid, whose reproducible-builds process rebuilds the app and compares it bit-for-bit against the published artifact. The build is deterministic by design — the Gradle version catalog (libs.versions.toml) pins all dependency and plugin versions, and AGP/Kotlin/KSP are pinned. Determinism is actively protected: the foojay JDK auto-provisioning resolver plugin was deliberately removed from settings.gradle.kts (and must not be re-added) because it would make the compile toolchain network-dependent and non-reproducible, and build-time-only steps (SBOM generation, jniLibs packaging exclusions, and the newly added ktlint check) are kept off the release-assembly path so they do not affect the APK output. The separate Gradle daemon-JVM provisioning in gradle-daemon-jvm.properties may still fetch the JVM that runs Gradle itself, but that is independent of the compile toolchain and does not affect the externally verified artifact reproducibility. This external reproducibility is the F-Droid (Android) path. The iOS release is reproducible too, self-verified: make release-ios builds the archive twice from a clean checkout on the pinned Xcode and refuses to stage unless the two unsigned Potillus.app payloads are byte-for-byte identical (the code signature is excluded — it is inherently signing-time- and nonce-dependent, and Apple re-signs on delivery). Unlike F-Droid there is no independent third-party rebuilder for iOS, so this guarantee is self-attested on a fixed toolchain rather than externally verified.

The software is installed and uninstalled using the platform's standard convention for Android apps. Installation is via F-Droid (with Google Play planned), the platform's package-manager/app-store mechanism, or by side-loading the signed APK; uninstallation uses Android's built-in uninstall flow (long-press the app or Settings → Apps). The app installs no system or root components and stores all data in its sandbox, so a normal uninstall removes it completely. The README "Quick start" documents the installation path. On iOS the planned distribution is the Apple App Store, the platform's standard install, update, and uninstall mechanism, which sandboxes the app the same way.

DESTDIR/PREFIX-style variables apply to make install-type installations into filesystem prefixes (typical of C/Autotools projects). An Android application has no such installation system: where the app is placed is decided by the operating system's package installer (F-Droid/Play/the Android package manager), not by a project-provided install step, so there is no location-selection stage that could honor DESTDIR or PREFIX.

It is easy to get started developing the software. The project builds two native apps from one repository. The Android app is a standard Gradle project: cloning the repository and running the bundled Gradle wrapper (./gradlew) builds it with no manual Gradle installation, and all dependency and plugin versions are pinned in the version catalog with repositories preconfigured in settings.gradle.kts, so a fresh checkout builds without additional setup. Developers can import it into Android Studio or run ./gradlew assembleDebug and installDebug to see changes on an emulator or device. CONTRIBUTING.md (architecture, build/test commands, release checklist) and the README's "Technical Aspects" document the path from clone to a running build. The iOS port is just as easy to start: make ios regenerates the Xcode project with XcodeGen from ios/project.yml (the .xcodeproj is generated, not committed) and builds via the Swift toolchain, and swift test in ios/PotillusKit runs the package suite — a fresh checkout builds with no manual project setup.

External dependencies are declared in a computer-processable, versioned form and are obtained automatically by a standard build. The Gradle version catalog (android/gradle/libs.versions.toml) pins every library and plugin version in its [versions], [libraries], and [plugins] tables, referenced via alias(libs.…) in the build scripts; settings.gradle.kts configures the repositories (google, mavenCentral, gradlePluginPortal), so ./gradlew resolves and downloads all declared dependencies with no manual steps. The build additionally generates a CycloneDX 1.6 JSON SBOM of the release dependencies as a standardized machine-readable inventory. On iOS the single external dependency (GRDB.swift) is declared and pinned in the SwiftPM manifest, resolved reproducibly from the pinned version.

The project checks its external dependencies for known vulnerabilities before every release, enforced at staging. As documented in SECURITY.md ("Dependency monitoring") and enforced by the CONTRIBUTING.md §7 release checklist, dependencies are scanned before each release with osv-scanner (a FLOSS scanner querying the OSV database) against the CycloneDX SBOM the build generates. Reported issues are triaged: exploitable vulnerabilities are fixed by upgrading or mitigating the affected dependency; non-exploitable ones are recorded as such.

The project uses externally-maintained components throughout, declared and version-pinned in the Gradle version catalog, with no vendored/convenience copies of third-party source that could silently go stale. The stack is kept current (modern AndroidX/Jetpack/Compose libraries, AGP 9 with built-in Kotlin, KSP), keeping it up to date is an explicit roadmap goal ("stay current and maintained"), and the documented pre-release osv-scanner check (see SECURITY.md, "Dependency monitoring") prevents the project from locking itself into outdated versions with known vulnerabilities, since findings are resolved by upgrading. The iOS app has exactly one third-party dependency, GRDB.swift (MIT), declared and version-pinned in the Swift package manifest with no vendored copy, kept current under the same "stay maintained" roadmap goal.

The project avoids deprecated or obsolete APIs and enforces this automatically: Kotlin's allWarningsAsErrors and Android Lint's warningsAsErrors promote deprecation warnings to build-breaking errors, so using a deprecated API fails the build. The technology stack is modern and actively maintained (current Jetpack Compose/AndroidX APIs, KSP instead of the older kapt, minSdk 30 avoiding legacy-compatibility workarounds), and the roadmap goal of staying current keeps the interfaces in use aligned with upstream releases; the warnings-as-errors gate is configured in android/app/build.gradle.kts. The iOS app targets a current, actively-maintained stack (iOS 17 SwiftUI, the Observation framework, String Catalogs) and no deprecated replacements; SwiftLint --strict is the automated lint gate. (Unlike Android, iOS does not promote compiler deprecation warnings to build errors; currency is maintained by the modern minimum target and review rather than a warnings-as-errors flag.)

The automated test suites now run on every change rather than only before a release. On the read-only GitHub mirror, every push to every branch runs the JVM unit tests and the Kover coverage floor (android.yml) and the PotillusKit suite with its coverage floor on a macOS runner (ios.yml); the on-device Compose UI and Espresso suite runs on an API 36 emulator (device-tests.yml) whenever anything under android/ changes, and weekly regardless. These need an SDK, KVM and macOS, which is precisely why they live on the mirror: the canonical GitLab pipeline (.gitlab-ci.yml) stays device-free and carries the checks that gate a merge. The iOS tests that require a booted simulator (app-target XCTests and XCUITests) are the remaining part still run locally before a release; see docs/MIRROR-CHECKS.md for the full scope and its limits.

For well over 50% of the bugs fixed in the recent release history, the project added a regression test or an automated check that prevents recurrence. Examples of regression tests: LocaleFormattingInstrumentedTest (added with the fix for incorrect system-language number/date formatting in exports on API 30–32), NumberFormatTest (pinning the decimal separator after a locale-dependent formatting bug), and a white-box assertion in BackupRepositoryInstrumentedTest added with a backup fix. In addition, defect fixes were routinely paired with new invariants in the automated release-check gate (tools/release-check.sh) — e.g. version-string and locale-consistency checks and current-version locale-coverage checks — and with re-enabled lint checks (such as PluralsCandidate) that catch the class of bug going forward. Together these mean the majority of recent fixes are covered by automated regression protection. The iOS port is guarded the same way: its behaviour is pinned to Android's by the shared golden test vectors (SchemaParityTests), so a fixed cross-platform discrepancy stays fixed.

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.

The project has a formal written policy mandating tests for new functionality. CONTRIBUTING.md §5 ("Test policy (mandatory)") states that as major new functionality is added, automated tests covering it MUST be added to the project's automated test suite as part of the same change, and that a change introducing significant new behavior without accompanying tests will not be merged. This is reinforced by the domain-layer coverage-floor rules in the same section.

The project's documented instructions for change proposals include the test-addition policy. CONTRIBUTING.md §2 ("Submitting changes"), step 3, states that per the mandatory test policy in §5, major new functionality MUST include automated tests covering it in the same change, and that ./gradlew test must pass and the release gate must stay green. The full policy is defined in §5. The same policy covers the iOS Swift suite; make check-swift-tests guards that added Swift tests actually assert.

The project is maximally strict with warnings. The Kotlin compiler runs with allWarningsAsErrors = true, so every compiler warning fails the build, and Android Lint runs with warningsAsErrors = true and abortOnError = true, promoting every lint warning to a build-breaking error. Rather than suppressing warnings, the project removes their causes and re-enables checks once underlying tooling bugs are fixed (e.g. the PluralsCandidate and WrongStartDestinationType lint checks were restored after workarounds were no longer needed). ktlint was additionally added as a style checker. These gates are configured in android/app/build.gradle.kts. On the iOS side the strictness gate is SwiftLint (a FLOSS linter pinned to version 0.65.0), run as part of make ios; Swift compiler warnings-as-errors are not currently enforced.

The project implements secure design principles. Least privilege / minimal attack surface: the app holds no network permission and requests no camera, microphone, location, contacts, or runtime-storage permissions. Secure defaults: it is offline-only with no tracking, analytics, or ads by design; data stays in the app sandbox; and the preferences store is sealed with an AES-256-GCM key in the hardware-backed Android Keystore. Economy of mechanism: a small, focused architecture with a framework-free domain layer and no unnecessary services. Fail-safe input handling: importers validate input and the CSV exporter neutralizes formula injection (OWASP "CSV Injection"), with migration tests protecting data integrity. Defense in depth: an optional biometric lock supplements the platform sandbox. These are documented in SECURITY.md ("Security model") and PRIVACY.md. The SwiftUI port embodies the same principles on Apple's platform: the App Sandbox and no network entitlement, the key in the iOS Keychain (SecretKeyProviding), and the same defensive backup parsing; iOS-specific hardening refinements (e.g. an explicit ATS declaration) are tracked in docs/ROADMAP.md.

The software's default security mechanisms use only strong, modern cryptography and none of the known-weak algorithms or modes. The encrypted preferences store uses AES-256 in GCM (authenticated encryption) — not ECB, CBC, DES/3DES, or RC4 — with the key held in the hardware-backed Android Keystore, a 96-bit random IV per encryption drawn from a cryptographically secure RNG, and a 128-bit authentication tag. No weak hash functions (e.g. MD5 or SHA-1) are used in the security mechanisms (implemented in KeystoreSecretStore.kt). The iOS path uses the same modern AEAD construction (AES-256-GCM via CryptoKit), avoiding the broken or weak algorithms the criterion warns against.

The application processes no authentication credentials (no passwords, tokens, logins, or network authentication) and stores no key files. Its only cryptographic key is an AES-256-GCM key generated inside the hardware-backed Android Keystore; the raw key material never leaves the secure hardware and is never written to a file, so there are no user-managed credential or key files to store separately or replace without recompilation. (For context, the Keystore key is already isolated from configuration, database, and logs and could be rotated by deleting its alias, but this is not user-facing credential management.)

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 application does not use TLS and performs no network communication (no INTERNET permission, offline-only), so there are no TLS connections and no certificate verification to assess.

The application does not use TLS and performs no network communication (no INTERNET permission, offline-only); it never sends HTTP headers or any private information over a network, so there is nothing to verify before transmission.

Releases are cryptographically signed with the maintainer's own Android app-signing key via reproducible builds; the private key is held only by the maintainer and is never stored on GitLab, F-Droid, or any other distribution site. SECURITY.md ("Verifying releases") documents how users obtain the public key and verify a release: the F-Droid client verifies the signature automatically and the project's F-Droid metadata pins the allowed signing key; users can also compare the APK signing certificate SHA-256 fingerprint (7506f17184b31a2d67621305d190a73e497806b39f7d64463ff5dbc0afd8317b) via apksigner verify --print-certs, or reproduce the build and compare. This author-signing model is the one used by the productive channels (GitLab and F-Droid). The planned app-store channels follow each store's own signing model instead: with Google Play App Signing the developer signs the upload with an upload key and Google re-signs the distributed APK with a Google-held key; with the Apple App Store the developer signs with a distribution certificate and App Store Connect re-signs the app with an Apple identity. On those channels the store, not the maintainer, holds the distribution signing key — a property of the platforms, not a project choice.

Release tags are cryptographically signed and verifiable. Per the CONTRIBUTING.md §7 release checklist, each release tag is created as a GPG-signed annotated tag (git tag -s) using the maintainer's key (fingerprint 1842 323B 4FCF 9B90 995F A17F A350 B991 F05A 4857, available from keyring.debian.org — the same key used for security reports); the checklist also documents enabling git config tag.gpgSign true so annotated tags are signed automatically. SECURITY.md ("Verifying releases") documents how to import the key and verify a tag with git tag -v.

The application validates inputs from its potentially untrusted sources using an allowlist approach. JSON backup/import is validated on restore (structure and values) and invalid or foreign data is rejected, covered by BackupRepositoryInstrumentedTest. Numeric user inputs (drink amounts, body weight, limits) are checked for valid ranges/format, with the amount dialog entering a controlled error state rather than accepting bad values, and locale-dependent number parsing is handled deliberately (regression-tested by NumberFormatTest). Room migrations validate the database schema on upgrade (MigrationTest). As output-side hardening, the CSV exporter neutralizes formula injection (OWASP "CSV Injection"). Since the app uses no network, its untrusted inputs are essentially user entries and imported files, both of which are validated. The iOS port validates the same untrusted inputs: it reads and writes the identical JSON backup format, with its parser pinned to Android's behaviour by the shared golden test vectors (SchemaParityTests).

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.

The project provides a security assurance case in docs/ASSURANCE_CASE.md (linked from SECURITY.md). It takes the security requirements from SECURITY.md, describes the threat model (assets, in-scope adversaries/attacks, and explicit out-of-scope residual risks), identifies the trust boundaries (app sandbox, hardware-backed Keystore, FLAG_SECURE screen boundary, device/biometric authentication, the export boundary, and the absence of a network boundary), argues that secure design principles were applied (least privilege, secure defaults, economy of mechanism, defense in depth, fail-safe), and maps common implementation weakness classes to their countermeasures (injection, insecure storage, cryptography, input validation, network exposure, memory safety, tampering, and upgrade data integrity).

The static analysis tool used for static_analysis — Android Lint — includes a dedicated set of security detectors that look for common Android-environment vulnerabilities (e.g. exported components and permission issues, cleartext traffic, hardcoded credentials, weak cryptography, unsafe WebView/TrustManager patterns, and SQL-injection/path-traversal hints). The build runs Lint with abortOnError = true and warningsAsErrors = true, so such findings are enforced as build-breaking errors rather than merely reported. This is complemented by osv-scanner dependency scanning (SECURITY.md, "Dependency monitoring"). The Lint gate is configured in android/app/build.gradle.kts. On the iOS side SwiftLint — a FLOSS linter pinned to version 0.65.0 — runs as a make ios gate over the Swift sources, so lint findings are caught before a build ships.

The software is written entirely in memory-safe languages: Kotlin on the JVM/ART runtime for the Android app and Swift for the iOS app, both with automatic memory management and no manual allocation, pointer arithmetic, or buffer handling. Neither build produces memory-unsafe (C/C++/NDK) code, so there is no unsafe memory use for a dynamic analysis tool to detect.