saphid--frame-control/.claude/NOTES-user-repos.md

User repositories

Scope: ui/apk_sources/fdroid.py, fixture tests and docs/apk-repos.md. No headset access. No delegation or independent reviewer launched: task explicitly forbids delegation; parent integrates and reviews. Existing catalogue API stays unchanged.

Decisions:

• Support F-Droid signed v2 and v1, HTTPS only, RSA PKCS#1 CMS/JAR verification.
• Pin operator certificate fingerprints. Without a supplied fingerprint, verify the complete signature chain of hashes on first use, then persist that signer.
• Reuse frame_catalog._IndexReader and _reduce_index; keep authenticated source cache separate from legacy unauthenticated catalogue cache to avoid laundering trust.
• Sources list compatible builds (Android <=30, arm64 or no native code), as existing catalogue reducer does. This is compatibility filtering, not a runtime guarantee.
• No Obtainium export import or new unsigned JSON format in this source.

Research: downloaded F-Droid API/setup docs, Obtainium and SideQuest READMEs, Izzy repo page and entry.jar via HTTPS. Izzy's published fingerprint matched pure-Python CMS validation: 3BF0D6ABFEAE2F401707B6D966BE743BF0EEE49C2561B9BA39073711F628937A.

Final verification

All commands below ran in /Users/saphid/projects/steam-frame-userrepo on user-repos.

• python3 --version: Python 3.9.6.
• python3 -m unittest discover -s tests -p test_fdroid_sources.py: initially 13 tests, OK, exit 0. Added a cache-corruption test afterward.
• Final python3 -m unittest discover -s tests: 180 tests in 6.866s, OK, exit 0 (includes 14 source tests and existing catalogue/version tests).
• python3 ui/apk_sources/fdroid.py add 'https://apt.izzysoft.de/fdroid/repo?fingerprint=3BF0D6ABFEAE2F401707B6D966BE743BF0EEE49C2561B9BA39073711F628937A' --name 'IzzyOnDroid verification': exit 0; saved fdroid-user-57e98c13877f14fdea65 with the published pin.
• python3 ui/apk_sources/fdroid.py search fdroid-user-57e98c13877f14fdea65 'tinymusicplayer': exit 0; com.martinmimigames.tinymusicplayer, version 1.3 / code 4, GPL-3.0-only, 16,520 bytes.
• python3 ui/apk_sources/fdroid.py download fdroid-user-57e98c13877f14fdea65 com.martinmimigames.tinymusicplayer: exit 0, verified true. Independent hashlib readback matched d7bcb24d101b04beb3394b695b24be4e2c3d6ed702f1d0e06bc4dd707f64d86a.
• Direct _fetch + _jar calls on F-Droid main/archive entry.jar: exit 0; both matched the published 43238d512c1e5eb2d6569f4a3afbf5523418b82e0a3ed1552770abb9a9c9ccab pin.
• .claude/user-repos-proof.json retains live CLI results and APK readback. Live APK remains in the per-user apk-sources cache; the added source remains in the per-user apk-repos.json, as requested for the real add/search/download run.

Not verified: headset installation/runtime, native UI/server integration (sibling worker), real v1-only server (offline signed fixture covers fallback), executing the fdroidserver publishing instructions, full F-Droid main/archive index/APK downloads (their live signed entry jars were checked). No independent reviewer was run because this task forbids delegation and assigns review to the parent.

Known limits / follow-up questions: only one RSA-2048–8192 JAR signer supported; no ECDSA/DSA/PSS or section-only SF signatures; no index timestamp rollback or expiry policy, automated key rotation or cross-process settings-write locking. The settings API serializes threads and publishes atomically. Should a later change add explicit rollback policy and broader JAR algorithms? Parent may choose UI wording for TOFU; this source already returns trust_on_first_use.

Artwork follow-up

Added images: {icon, banner, screenshots}, matching top-level icon, developer from authorName, and HTML/entity-aware one-line summaries. Artwork prefers en-US per field, then the first populated locale. Phone screenshots precede seven-inch screenshots, with at most six unique URLs. v2 supports both screenshots.phone/sevenInch and the older phoneScreenshots/sevenInchScreenshots field names. v1 localized filenames are resolved under package/locale, with legacy top-level icons resolved under icons/. Missing art remains null/empty.

No frame_catalog edit was necessary: this source already rereads raw metadata after using the shared compatibility reducer. Incremented the source cache schema so old entries refresh immediately rather than hiding artwork for a day. Tests exercise v1/v2 metadata, cache round-trips and migration, locale fallback, missing fields, legacy icon paths, screenshot bounds and summary cleanup.

Follow-up verification (Python 3.9.6, branch user-repos):

• python3 -m unittest discover -s tests -p test_fdroid_sources.py: 19 tests, 0.046s, OK, exit 0.
• python3 -m unittest discover -s tests: 185 tests, 5.081s, OK, exit 0.
• git diff --check: exit 0. No live image fetch or redesigned store rendering was exercised; these remain with the parent/UI integration. No independent review or delegation performed, as explicitly requested. No new open implementation questions.