From 80a4e62a49ef1b7483745f8672e873cc476dd693 Mon Sep 17 00:00:00 2001 From: Cogential Date: Wed, 21 Oct 2026 00:08:05 -0400 Subject: [PATCH] CLAUDE.md: auth and settings-file rules, and the review fixes still to do Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01C3G4bF9bag9rHEh1Anvngi --- CLAUDE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4add231 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,24 @@ +# 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=` 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 `), 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).