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