# Flathub Submission Readiness

Tracks OrbitHub's readiness for submission to Flathub. This is a separate
checklist from `docs/PROGRESS.md`'s development milestones, since Flathub
submission is an external process with its own requirements.

## Status

| Item | Status |
|---|---|
| Production manifest with pinned, reproducible git source | Done — `packaging/flatpak/flathub/org.darksingularity.OrbitHub.yml`; commit pin updated at each tagged release |
| `flathub.json` for build settings (`only-arches`, etc.) | Done — `packaging/flatpak/flathub/flathub.json` |
| Offline build (no network fetches during build) | Verified — no `FetchContent`/`ExternalProject`/`curl`/`wget` in CMake; all vendored deps committed in `third_party/`; confirmed with a real `flatpak-builder` build |
| SSH client available inside the sandbox | Verified — provided by the `org.kde.Platform` runtime base, no packaging needed |
| `--filesystem=home` removed | Done — narrowed to `--filesystem=~/.ssh` (read-write, needed for `known_hosts` and SSH config) |
| SSH known-hosts trust persists with narrowed permissions | Verified in sandbox against real infrastructure |
| RDP works with zero filesystem permission | Verified — FreeRDP's cert trust store lives outside the sandboxed home path concerns entirely (see below) |
| Private-key/export file pickers use the desktop portal | **Verified interactively** — `QFileDialog`'s Browse button correctly opens the native GTK portal chooser ("Select Private Key"), which can browse the full filesystem via user consent regardless of the sandbox's static `~/.ssh`-only grant |
| Current, supported KDE runtime | Verified — upgraded to `6.11` (linter's recommended latest); confirmed the app still builds and launches against it |
| Desktop entry validates | Verified |
| Application icon validates | Verified — PNGs at all standard hicolor sizes, matching the real app icon |
| MetaInfo/AppStream validates | Verified via both `appstreamcli validate` and Flathub's own `flatpak-builder-lint appstream` (0 errors either way) |
| Screenshots present | Done — profiles view, active SSH session, active RDP session, all captured against real (test) infrastructure |
| Release information present | Done — `<releases>` block with `v2026.9.8` (add an entry per future tagged release) |
| Developer/project URLs present | Done — homepage, bugtracker, vcs-browser, developer block |
| Architecture support decided | `x86_64` only (no ARM hardware available to test FreeRDP/WinPR on aarch64), set via `flathub.json`'s `only-arches` |
| Flathub manifest linter passes | One expected finding remains: `finish-args-ssh-filesystem-access` (see below) — everything else passes, including `only-arches` placement and runtime-version currency |
| AppStream linter passes | Passing (both `appstreamcli validate` and `flatpak-builder-lint appstream`) |
| Clean install works without host dependencies | Verified via local `.flatpak` bundle install and launch, on both KDE 6.10 and 6.11 runtimes |
| Bundled-dependency license files installed per Flathub's `$FLATPAK_ID` convention | Partially done — path fixed from `share/licenses/orbithub` to the required `share/licenses/org.darksingularity.OrbitHub`; FreeRDP's and KodoTerm's `LICENSE` files now installed there too. **`libvterm`'s vendored copy has no `LICENSE`/`COPYING` file at all** — needs to be pulled from upstream and added as `third_party/libvterm/LICENSE` before submission (README claims MIT; not verified against an actual license file in-tree) |

## ⚠️ Not yet addressed: Generative AI disclosure policy is a real acceptance risk, not a checklist item

See the dedicated section below — unlike everything else on this page, this
isn't something more packaging work resolves.

### `finish-args-ssh-filesystem-access` — expected, needs a submission-time justification

Flathub's linter flags *any* `~/.ssh` filesystem grant by policy — it's not a
bug in this manifest, it's a deliberate prompt for the submitter to justify
the access during PR review. Checked the linter's own exceptions list:
several existing SSH-client apps already have this exact permission approved
with justifications like *"Read-only access to ~/.ssh is required to load
SSH keys for connecting to devices over SSH"* and *"Needed to manage SSH keys
and configurations for connections"* — OrbitHub's case is the same pattern
(read-write, specifically for `known_hosts` persistence and default identity
file discovery). Include a similar justification in the submission PR.

## ⚠️ Not yet addressed: Generative AI disclosure policy

Flathub's [Generative AI policy](https://docs.flathub.org/docs/for-app-authors/requirements#generative-ai-policy)
requires submitters to disclose "any AI-generated code, documentation,
packaging, or other material" included in the app or its Flathub packaging,
identifying "the affected parts and approximate extent." This is not a
formality — it's evaluated at reviewer discretion, and reviewers may reject
"based on the extent or role of generated material."

OrbitHub's development has used Claude Code extensively — the app's C++
source, this Flatpak packaging (manifest, metainfo, build scripts), and this
tracking doc itself. Every commit in this repository carries a
`Co-Authored-By: Claude Sonnet 5` trailer, which is itself effectively an
existing disclosure trail. An honest submission disclosure needs to reflect
that extent truthfully — not a token "some AI assistance was used" note.

The same policy also prohibits AI tools from opening or automating the
submission PR itself, or generating its commit messages, description, or
review replies. **This means the actual submission PR — including its AI
disclosure — has to be written and opened by a human, not drafted by
Claude.** Not done, and not something this repo's tooling should attempt.

This is a real acceptance risk that no amount of technical packaging work
resolves — it's a policy/reviewer-discretion matter, separate from every
other item on this page.

## Related finding (not a packaging blocker)

During permission-narrowing research, RDP certificate verification was found
to be completely disabled (`IgnoreCertificate=TRUE`, all server certificates
silently accepted including *changed* ones). This has been fixed separately
in `src/rdp_session_backend.cpp` — FreeRDP's own trust-on-first-use
certificate store is now used, matching SSH's known-hosts model. Not a
Flathub-specific issue, but worth noting since it was found in the course of
this work.

## Explicitly out of scope for this repo

- Opening the actual submission PR against `github.com/flathub/flathub` —
  requires the maintainer's GitHub identity, done outside this repo, and per
  the Generative AI policy above must be written by a human, not drafted here.
- ARM64 build/testing — no hardware available.
- Flathub's post-acceptance developer-verification step — done via
  Flathub's own website after acceptance, using DNS control of
  `darksingularity.org`.

## Files

- Dev manifest (local iteration, `type: dir`): `packaging/flatpak/org.darksingularity.OrbitHub.yml`
- Flathub submission manifest (pinned `type: git`): `packaging/flatpak/flathub/org.darksingularity.OrbitHub.yml`
- AppStream metainfo: `packaging/linux/org.darksingularity.OrbitHub.metainfo.xml`
- Desktop entry: `packaging/linux/org.darksingularity.OrbitHub.desktop`