History service
The history service keeps the history History Sync sends, on the Firewalla,
where the child can’t read, edit or delete it. It’s filter/history/historyd.py:
Python, standard library only, in its own container on port 8092. The
design note has the reasons.
- Append-only. History Sync sends each file’s new bytes with the offset they start at, and the service takes them only at its own end of the file. No route edits or deletes anything.
- Rolling window: 90 days. Every 6 hours it deletes day files older than that, but only those the archive Mac has reported holding with the same size and checksum. If the archive Mac is off for weeks, it simply keeps more.
- Capped, so the filter beside it is safe: 1 GB and 5000 files per device, and always 512 MB of the disk left free.
Tokens
Section titled “Tokens”Stored as hashes in tokens.json:
| Role | Who | Can |
|---|---|---|
write |
History Sync, one per child device, bound to its folder | Append to that device’s files |
read |
Each parent’s viewer and phone | List and read |
archive |
The archive Mac’s viewer | Read, report what it holds, and make read tokens for phones |
filter/scripts/history-token.sh add <role> <whose> makes one. It saves the
token in a private file and never shows it. list and remove <id> manage
them. The child’s Mac gets its token from the History Sync Lock profile, so the
child can’t change it.
| Route | Who | |
|---|---|---|
GET /api/history/health |
anyone | ok |
PUT /api/history/files/<device>/<path>?offset=N |
write | Append the body at offset N, which must be the current size (else 409 with the size). heartbeat.json and report.txt are replaced. 507 when over the cap |
GET /api/history/files[?device=D] |
read, archive | Every file’s path, size, mtime and checksum |
GET /api/history/files/<device>/<path>?offset=N |
read, archive | The bytes from N |
POST /api/history/archived {files} |
archive | What the archive now holds |
GET /api/history/status |
read, archive | The window, devices, the last archive report |
GET/POST /api/history/tokens, DELETE /api/history/tokens/<id> |
archive | Read tokens for phones (“Connect a phone”) |