Libellus Potionis

Projects that follow the best practices below can voluntarily self-certify and show that they've achieved an Open Source Security Foundation (OpenSSF) best practices badge.

There is no set of practices that can guarantee that software will never have defects or vulnerabilities; even formal methods can fail if the specifications or assumptions are wrong. Nor is there any set of practices that can guarantee that a project will sustain a healthy and well-functioning development community. However, following best practices can help improve the results of projects. For example, some practices enable multi-person review before release, which can both help find otherwise hard-to-find technical vulnerabilities and help build trust and a desire for repeated interaction among developers from different companies. To earn a badge, all MUST and MUST NOT criteria must be met, all SHOULD criteria must be met OR be unmet with justification, and all SUGGESTED criteria must be met OR unmet (we want them considered at least). If you want to enter justification text as a generic comment, instead of being a rationale that the situation is acceptable, start the text block with '//' followed by a space. Feedback is welcome via the GitHub site as issues or pull requests There is also a mailing list for general discussion.

We gladly provide the information in several locales, however, if there is any conflict or inconsistency between the translations, the English version is the authoritative version.
If this is your project, please show your baseline badge status on your project page! The baseline badge status looks like this: Baseline badge level for project 13480 is baseline-2 Here is how to embed the baseline badge:
You can show your baseline badge status by embedding this in your markdown file:
[![OpenSSF Baseline](https://www.bestpractices.dev/projects/13480/baseline)](https://www.bestpractices.dev/projects/13480)
or by embedding this in your HTML:
<a href="https://www.bestpractices.dev/projects/13480"><img src="https://www.bestpractices.dev/projects/13480/baseline"></a>


These are the Baseline Level 2 criteria. These are criteria version v2026.08.28.

Baseline Series: Baseline Level 1 Baseline Level 2 Baseline Level 3

        

 Basics

  • General

    Note that other projects may use the same name.

    Libellus Potionis is a privacy-first, free, open-source, and ad-free alcohol consumption tracker designed to help users monitor, pace, and manage their drinking habits entirely offline. It requires no invasive device permissions—no camera, microphone, or location access—and completely operates without network connectivity. It runs on both Android and iOS, and is available on F-Droid.

    Please use SPDX license expression format; examples include "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "GPL-2.0+", "LGPL-3.0+", "MIT", and "(BSD-2-Clause OR Ruby)". Do not include single quotes or double quotes.
    If there is more than one language, list them as comma-separated values (spaces optional) and sort them from most to least used. If there is a long list, please list at least the first three most common ones. If there is no language (e.g., this is a documentation-only or test-only project), use the single character "-". Please use a conventional capitalization for each language, e.g., "JavaScript".
    The Common Platform Enumeration (CPE) is a structured naming scheme for information technology systems, software, and packages. It is used in a number of systems and databases when reporting vulnerabilities.

    The two are separate native apps in this one repository — Kotlin/Jetpack Compose for Android, Swift/SwiftUI for iOS — that share the same design, the same feature set, and a common JSON backup format, so a backup exported on one platform imports on the other. Their behaviour is kept in lock-step by a shared set of golden test vectors.

    Key Features

    • Logging: predefine custom beverages or use internationally common presets. Log drinks instantly or retroactively with precise timestamp corrections.
    • Concurrent limits: set three boundaries at once — a daily limit in grams of pure alcohol, a rolling 7-day limit in grams, and a maximum number of drinking days per week. Each has its own progress bar.
    • Blood alcohol concentration (BAC): enter your body weight to get a live estimate from the Widmark formula.
    • Counseling reports: generate a two-page PDF report of your consumption for a counseling appointment.
    • Data portability: export the dataset as a CSV file for external processing (e.g. in LibreOffice Calc), or create JSON backups to move data between devices.
    • Adjustments: set your own "day start" time, so that late-night drinks count toward the preceding evening, and an evaluation start date for a clean restart.

    A User's Guide is available inside the app.

 Controls 19/19 ●

  • Controls


    Enough for a badge!

    When a CI/CD task is executed with no permissions specified, the CI/CD system MUST default the task's permissions to the lowest permissions granted in the pipeline. [OSPS-AC-04.01]
    Configure the project's settings to assign the lowest available permissions to new pipelines by default, granting additional permissions only when necessary for specific tasks.

    The project's CI/CD pipeline (.gitlab-ci.yml) runs with the minimum privileges its tasks require, which for a checks-only pipeline is none beyond reading the checkout. No job defines any secret, variable or protected credential; none runs in privileged mode or with a custom service account; and every job is read-only — it runs tools/release-check.sh --Werror, make check-static or osv-scanner over the checked-out tree and writes nothing back. The privileged credentials the project holds (the release-signing keystore, the store-upload keys, the GitLab release token) exist only in the maintainer's local, git-ignored files and are never present in the CI environment; releases are built and published manually with Fastlane and the Makefile targets on a trusted local checkout. The automatic CI job token is scoped to this project alone under Settings > CI/CD > Token Access. See also the related OSPS-AC-04.02 and OSPS-BR-01.04.


    Enough for a badge!

    When an official release is created, that release MUST be assigned a unique version identifier. [OSPS-BR-02.01]
    Assign a unique version identifier to each release produced by the project, following a consistent naming convention or numbering scheme. Examples include SemVer, CalVer, or git commit id.

    Every user-facing release has a unique version identifier. The app carries a three-part versionName (MAJOR.MINOR.PATCH) and a strictly increasing integer versionCode, both defined in android/app/build.gradle.kts. CONTRIBUTING.md requires that the versionName, the top CHANGELOG.md entry, the README title, and the proguard-rules.pro header all carry the same version string and that versionCode increases by at least 1 each release; the tools/release-check.sh release gate enforces this consistency automatically. The iOS port carries the same single version: tools/gen-ios-version.py derives its MARKETING_VERSION from the top CHANGELOG.md entry and its CURRENT_PROJECT_VERSION from the same versionCode, writing both to the generated ios/Version.xcconfig, so the two apps release under one identifier.


    Enough for a badge!

    When an official release is created, that release MUST contain a descriptive log of functional and security modifications. [OSPS-BR-04.01]
    Ensure that all releases include a descriptive change log. It is recommended to ensure that the change log is human-readable and includes details beyond commit messages, such as descriptions of the security impact or relevance to different use cases. To ensure machine readability, place the content under a markdown header such as "## Changelog".

    Each release is accompanied by human-readable release notes in CHANGELOG.md: a curated summary (not raw version-control log output), with a concise subject line plus prose describing the major changes, typically separating user-facing changes from internal ones so users can judge the upgrade impact. Localized store release notes are additionally maintained per versionCode under fastlane/metadata/android/<locale>/changelogs/.


    Enough for a badge!

    When a build and release pipeline ingests dependencies, it MUST use standardized tooling where available. [OSPS-BR-05.01]
    Use a common tooling for your ecosystem, such as package managers or dependency management tools to ingest dependencies at build time. This may include using a dependency file, lock file, or manifest to specify the required dependencies, which are then pulled in by the build system.

    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 iOS port declares its dependencies the same way: ios/PotillusKit/Package.swift names them and ios/PotillusKit/Package.resolved pins each to an exact version and revision, which SwiftPM resolves automatically. Both builds additionally generate a CycloneDX 1.6 JSON SBOM of the release dependencies as a standardized machine-readable inventory (make sbom, make ios-sbom).


    Enough for a badge!

    When an official release is created, that release MUST be signed or accounted for in a signed manifest including each asset's cryptographic hashes. [OSPS-BR-06.01]
    Sign all released software assets at build time with a cryptographic signature or attestations, such as GPG or PGP signature, Sigstore signatures, SLSA provenance, or SLSA VSAs. Include the cryptographic hashes of each asset in a signed manifest or metadata file.

    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. The productive channels (GitLab, F-Droid) use this author-signing model; the planned store channels follow each store's own model instead. With the Apple App Store the developer signs with a distribution certificate and App Store Connect re-signs the app with an Apple identity (and Google Play App Signing re-signs with a Google-held key), so on those channels the store, not the maintainer, holds the distribution key — a property of the platforms, not a project choice.


    Enough for a badge!

    When the project has made a release, the project documentation MUST include a description of how the project selects, obtains, and tracks its dependencies. [OSPS-DO-06.01]
    It is recommended to publish this information alongside the project's technical & design documentation on a publicly viewable resource such as the source code repository, project website, or other channel.

    The project's documentation describes how it selects, obtains, and tracks dependencies. Selection: CONTRIBUTING.md states "Minimal dependencies: every library must justify its presence; prefer AndroidX stable releases over alpha/beta". Obtaining: docs/NOTICES.md documents that all third-party libraries are consumed exclusively as Gradle build dependencies declared by exact Maven coordinates in android/gradle/libs.versions.toml, never vendored. Tracking: versions are pinned in that catalog; a CycloneDX SBOM is generated for every release as the authoritative inventory; and dependencies are scanned with osv-scanner against that SBOM as an enforced gate before every release, per SECURITY.md ("Dependency monitoring"). The iOS port declares its dependencies the same way: ios/PotillusKit/Package.swift selects them and ios/PotillusKit/Package.resolved pins each to an exact version and revision, with a CycloneDX SBOM generated from that lockfile (tools/gen-ios-sbom.py, make ios-sbom).


    Enough for a badge!

    The project documentation MUST include instructions on how to build the software, including required libraries, frameworks, SDKs, and dependencies. [OSPS-DO-07.01]
    It is recommended to publish this information alongside the project's contributor documentation, such as in CONTRIBUTING.md or other developer task documentation. This may also be documented using Makefile targets or other automation scripts.

    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.


    Enough for a badge!

    The project documentation MUST include a list of project members with access to sensitive resources. [OSPS-GV-01.01]
    Document project participants and their roles through such artifacts as members.md, governance.md, maintainers.md, or similar file within the source code repository of the project. This may be as simple as including names or account handles in a list of maintainers, or more complex depending on the project's governance.

    The project documentation lists the members with access to sensitive resources in docs/GOVERNANCE.md. The "Key roles" section names the sole role holder ("Maintainer / project lead"), and "Repository access and account security" states that write (push) access to the canonical repository is currently held only by the maintainer, who must have 2FA enabled. The document notes that any change in maintainers will be recorded there, so the list stays current while the project is active.


    Enough for a badge!

    The project documentation MUST include descriptions of the roles and responsibilities for members of the project [OSPS-GV-01.02]
    Document project participants and their roles through such artifacts as members.md, governance.md, maintainers.md, or similar file within the source code repository of the project.

    The project's key roles and responsibilities are documented in docs/GOVERNANCE.md ("Key roles"). The project currently has a single role — Maintainer / project lead, held by Martin A. Godisch (android@godisch.de) — with explicitly listed responsibilities: triaging and answering issues, reviewing and merging contributions, handling security reports, maintaining translations and documentation, and preparing and signing releases. It is clear who holds the role, and contributors take on no formal ongoing role beyond their individual contributions.


    Enough for a badge!

    The project documentation MUST include a guide for code contributors that includes requirements for acceptable contributions. [OSPS-GV-03.02]
    Extend the CONTRIBUTING.md or CONTRIBUTING/ contents in the project documentation to outline the requirements for acceptable contributions, including coding standards, testing requirements, and submission guidelines for code contributors. It is recommended that this guide is the source of truth for both contributors and approvers.

    CONTRIBUTING.md documents the requirements for acceptable contributions. Section 2 ("Submitting changes"), step 3, makes them a merge precondition and points to the relevant sections; Section 4 ("Coding conventions") names the required coding standard — the official Kotlin coding conventions — together with mandatory KDoc and constant/default/enum-persistence rules; Sections 3 (architecture) and 5 (testing) add the remaining acceptance rules. ./gradlew test and tools/release-check.sh must pass.


    Enough for a badge!

    The version control system MUST require all code contributors to assert that they are legally authorized to make the associated contributions on every commit. [OSPS-LE-01.01]
    Include a DCO in the project's repository, requiring code contributors to assert that they are legally authorized to commit the associated contributions on every commit. Use a status check to ensure the assertion is made. A CLA also satisfies this requirement. Some version control systems, such as GitHub, may include this in the platform terms of service.

    Contributions are governed by the Developer Certificate of Origin (DCO). CONTRIBUTING.md, Section 2, requires every commit to be signed off with a Signed-off-by line (via git commit -s) and links to developercertificate.org documenting what sign-off means for this project. This is the recommended lightweight legal mechanism by which contributors assert they are authorized to submit their contributions under the project's GPL-3.0-or-later license.


    Enough for a badge!

    When a commit is made to the primary branch, any automated status checks for commits MUST pass or be manually bypassed. [OSPS-QA-03.01]
    Configure the project's version control system to require that all automated status checks pass or require manual acknowledgement before a commit can be merged into the primary branch. It is recommended that any optional status checks are NOT configured as a pass or fail requirement that approvers may be tempted to bypass.

    Changes proposed to the primary branch (main) go through merge requests — main is a protected branch that no one may push to directly (see OSPS-AC-03.01) — and a GitLab CI pipeline runs automated status checks on every one of them. .gitlab-ci.yml restricts itself by workflow rule to merge requests targeting main and runs three jobs: the repository-wide release gate (tools/release-check.sh --Werror, warnings promoted to errors), the device-free static battery (make check-static), and an osv-scanner source scan of the committed lockfiles. The checks are enforced rather than advisory: the project setting 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 maintainer additionally runs the full battery including the test suites locally before merging.


    Enough for a badge!

    Prior to a commit being accepted, the project's CI/CD pipelines MUST run at least one automated test suite to ensure the changes meet expectations. [OSPS-QA-06.01]
    Automated tests should be run prior to every merge into the primary branch. The test suite should be run in a CI/CD pipeline and the results should be visible to all contributors. The test suite should be run in a consistent environment and should be run in a way that allows contributors to run the tests locally. Examples of test suites include unit tests, integration tests, and end-to-end tests.

    The project maintains automated test suites — JVM unit tests under android/app/src/test/ (domain, data, l10n, util and ViewModel layers, incl. LocaleSyncTest), instrumented tests under android/app/src/androidTest/, and the iOS PotillusKit suite plus app-target tests — and runs them before every release alongside the coverage gate; any contributor can run them locally (make -C android unit-tests; gmake ios). The MUST ('use at least one automated test suite') is thus satisfied in substance. This criterion is kept N/A rather than Met because its Details RECOMMEND running the suite inside the CI/CD pipeline, and the CANONICAL pipeline (.gitlab-ci.yml) runs the device-free checks only: GitLab's instance runners are a metered allowance, so a heavier SDK-bearing image is a cost question rather than a technical one, and the Swift package cannot be built on Linux at all because PotillusKit imports CryptoKit and Security. The suites DO run in CI on the read-only GitHub mirror — .github/workflows/android.yml runs the unit tests and the Kover floor, ios.yml runs the PotillusKit suite and its coverage floor on macOS, device-tests.yml runs the instrumented tests on an emulator, and codeql.yml builds both platforms — but the mirror carries no issues, no merge requests and no required checks (docs/MIRROR-CHECKS.md), so those runs are advisory and cannot block a change. Widening the canonical pipeline is tracked in docs/ROADMAP.md. Dependency risk in the meantime is covered by the osv-scanner SCA gate, which does run per merge request (see OSPS-VM-05.03).


    Enough for a badge!

    When the project has made a release, the project documentation MUST include design documentation demonstrating all actions and actors within the system. [OSPS-SA-01.01]
    Include designs in the project documentation that explains the actions and actors. Actors include any subsystem or entity that can influence another segment in the system. Ensure this is updated for new features or breaking changes.

    The software's high-level architecture is documented in CONTRIBUTING.md §3 ("Architecture rules"): it lists the major components (the data/, data/security/, domain/, l10n/, ui/, and util/ packages and their roles) and the relationships and layering constraints among them (the domain layer is framework-free and JVM-testable, Room types stay within the data layer, repositories expose only domain models, and ViewModels are context-free except SettingsViewModel). The README's "Technical Aspects" section additionally documents the key technologies and the manual dependency-injection approach (PotillusApp lazy singletons), Room, and Jetpack Compose. The SwiftUI port under ios/ mirrors this layering — a framework-free PotillusKit domain shared by the UI — and its behaviour is pinned to Android's by the shared golden test vectors in test-vectors/.


    Enough for a badge!

    When the project has made a release, the project documentation MUST include descriptions of all external software interfaces of the released software assets. [OSPS-SA-02.01]
    Document all software interfaces (APIs) of the released software assets, explaining how users can interact with the software and what data is expected or produced. Ensure this is updated for new features or breaking changes.

    The software is a GUI Android application; its external interface is the user interface together with the file formats it reads and writes, both documented in the User's Guide as reference material describing inputs and outputs. Inputs: drink logging, limit configuration, and body weight (used to estimate blood alcohol concentration via the Widmark formula). Outputs: the statistics screen (by week/month/year), a CSV export for spreadsheet processing, and a two-page PDF report. The JSON backup interface is documented for both directions — export produces a single JSON file containing all drinks and the complete log, and import offers explicit "replace" and "merge" modes. The iOS port is the same GUI application over the same inputs and outputs, reading and writing the identical JSON backup format (pinned to Android's by SchemaParityTests) and documented in the iOS User's Guide.


    Enough for a badge!

    When the project has made a release, the project MUST perform a security assessment to understand the most likely and impactful potential security problems that could occur within the software. [OSPS-SA-03.01]
    Performing a security assessment informs both project members as well as downstream consumers that the project understands what problems could arise within the software. Understanding what threats could be realized helps the project manage and address risk. This information is useful to downstream consumers to demonstrate the security acumen and practices of the project. Ensure this is updated for new features or breaking changes.

    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).


    Enough for a badge!

    The project documentation MUST include a policy for coordinated vulnerability disclosure (CVD), with a clear timeframe for response. [OSPS-VM-01.01]
    Create a SECURITY.md file at the root of the directory, outlining the project's policy for coordinated vulnerability disclosure. Include a method for reporting vulnerabilities. Set expectations for how the project will respond and address reported issues.

    The process for reporting vulnerabilities is published in SECURITY.md at the repository root (which GitLab surfaces as the project's security policy) and is linked from the README's "Security" section. Reporters are asked to disclose privately via PGP-encrypted e-mail to android@godisch.de rather than opening a public issue.


    Enough for a badge!

    The project documentation MUST provide a means for private vulnerability reporting directly to the security contacts within the project. [OSPS-VM-03.01]
    Provide a means for security researchers to report vulnerabilities privately to the project. This may be a dedicated email address, a web form, VCS specialized tools, email addresses for security contacts, or other methods.

    Private vulnerability reporting is the required path and SECURITY.md documents exactly how to send the information privately: a PGP-encrypted e-mail to android@godisch.de, using the maintainer's published key (fingerprint 1842 323B 4FCF 9B90 995F A17F A350 B991 F05A 4857), retrievable from the official Debian keyserver (hkps://keyring.debian.org:443). If a reporter cannot use PGP, the maintainer arranges a secure channel before any sensitive details are shared.


    Enough for a badge!

    The project documentation MUST publicly publish data about discovered vulnerabilities. [OSPS-VM-04.01]
    Provide information about known vulnerabilities in a predictable public channel, such as a CVE entry, blog post, or other medium. To the degree possible, this information should include affected version(s), how a consumer can determine if they are vulnerable, and instructions for mitigation or remediation.

    While active, the project publicly publishes data about discovered vulnerabilities through predictable public channels documented in SECURITY.md ("Security advisories"). Security-relevant fixes are recorded in the release notes (CHANGELOG.md) and the corresponding GitLab release, stating the affected version(s), how a user can determine whether they are affected, and the remediation — updating to the fixed version, distributed via F-Droid.



You can use tools and AI systems to propose changes via a simple URL, such as https://www.bestpractices.dev/en/projects/13480/choose/edit?osps_ac_01_01_status=Met&osps_ac_01_01_justification=GitHub+enforced. See our automation proposals system for how to do that. This data is available under the Community Data License Agreement – Permissive, Version 2.0 (CDLA-Permissive-2.0). This means that a Data Recipient may share the Data, with or without modifications, so long as the Data Recipient makes available the text of this agreement with the shared Data. Please credit Martin A. Godisch and the OpenSSF Best Practices badge contributors.

Project badge entry owned by: Martin A. Godisch.
Entry created on 2026-07-04 04:21:04 UTC, last updated on 2026-08-29 11:29:00 UTC. Last lost passing badge on 2026-07-19 18:17:51 UTC. Last achieved passing badge on 2026-07-19 18:18:14 UTC.