Cogential--frametanium/CLAUDE.md

Frametanium: notes for Claude sessions

See README.md for what it does. Service: manager.py (stdlib Python, runs on the Frame). Headset app: app/app.c.

Rules (from the 2026-10-20 review)

• Auth: every /api/* request needs a secret, loopback included. Headset app sends X-Frametanium-Key (app_key from ~/.config/frametanium/config.json), the page sends X-Key (the password). Both are generated by ensure_secrets(). Never add a loopback/no-password bypass, never accept secrets in the query string, and keep host_ok() (Host allow-list + Origin check). Any auth change must change app.c and page.html together, and old headset apps must still get a readable "#" notice in TSV replies.
• Write settings files only with save_json (unique temp + fsync; private=True for config.json) and do read-modify-writes under files_lock.
• Test locally: run manager.py with HOME=<scratch> and a config.json with another port; build app.c natively (gcc $(sdl2-config --cflags) app/app.c $(sdl2-config --libs)) and screenshot with SDL_VIDEODRIVER=dummy PM_SCREENSHOT=out.bmp PM_SCREEN=list.
• Don't push, tag, release or deploy without the user's OK.

Review fixes still to do (report: /data/cogent/reviews/2026-10-20/review-frametanium.md)

Done 2026-10-21: settings-file robustness (code-review 10, 11; security LOW 13), auth (security HIGH 1, 2, LOW 10, 12). Left, in this order: security MEDIUM 3 (Discover installs run install.sh without a confirm step), 4 (no integrity check: verify the GitHub asset digest; plan was an ed25519 signature for Frametanium's own updates, verified with openssl pkeyutl -rawin), 6 (tar symlink traversal, .tar.zst via GNU tar), 5 (workflow: SDL2 hash, pin actions by SHA), 7 (AppImage executed to unpack: prefer unsquashfs -o <ELF end>), LOW 8/9/11/14; then code-review bugs 1-9 and 12-16 (2: update Frametanium last in update_all; 4: Frametanium's own row needs a VERSION file).