Skip to content
Family Filter

History Sync

History Sync is a Mac app that sends this Mac’s Safari and Chrome history to the Firewalla’s history service and a shared folder, in the background, every 15 minutes and at login. Family Filter for Mac reads what it sends.

Build

Section titled “Build”
Terminal window
sync/scripts/build-app.sh      # builds release/History Sync.app

Needs Xcode’s command-line tools; runs on macOS 13 or later.

  • Signing: with the keychain’s Developer ID if there is one (SIGN_IDENTITY chooses another, - signs ad hoc). Full Disk Access is tied to the signature, so with ad-hoc signing every rebuild needs the grant again.
  • Notarizing: NOTARY_PROFILE=history-sync sync/scripts/build-app.sh builds, signs, submits to Apple, waits and staples the ticket, so the app opens on another Mac without warnings.

Setting it up

Section titled “Setting it up”
  1. Copy History Sync to Applications and open it.
  2. Full Disk Access: click Open Settings… and turn History Sync on. The window notices within a couple of seconds.
  3. Shared folder: choose it. Each Mac gets its own subfolder.
  4. Background sync turns itself on once there’s a folder. If it says Waiting for approval, allow it under Login Items.

Then quit. It keeps running with no window and no Dock icon.

Updating: quit it, then copy the new build over the old one. Full Disk Access stays granted because each build is signed with the same Developer ID.

How it works

Section titled “How it works”
  • One executable. Opened normally, it’s the setup window. launchd runs it as History Sync --agent: one push, then exit.
  • The launch job lives inside the app bundle and is registered with SMAppService. So the Full Disk Access granted to the app covers the background runs too.
  • Each run copies ~/Library/Safari/History.db and its WAL files, reads visits newer than the last one sent, and appends them to the day files.
  • Progress is kept by visit id, so each visit is sent once, even if a run is interrupted.

Chrome

Section titled “Chrome”

History Sync also sends Chrome, with no setup: each Chrome profile is sent beside Safari’s, in .chrome.csv files with one more column, browser. The Include Chrome history switch turns it off.

Each run also compares Chrome’s history with what it saw last time, and records deletions in events.csv.

The History Lock: the window’s Chrome section shows whether all eight Chrome History Lock policies are in force, whether this account is a standard user, and which other browsers are installed. "History Sync" --check-chrome prints the same and exits 1 if anything is wrong.

Safari report

Section titled “Safari report”

File ▸ Send Report to Shared Folder (⇧⌘R) writes report.txt into this Mac’s folder. It’s for deciding what else is worth syncing. It lists:

  • every table in Safari’s and Chrome’s history databases: schema, row count and sample rows;
  • Safari’s files;
  • the Chrome History Lock check;
  • other browsers installed, and when each one’s history last changed.

The sample rows contain real URLs and titles.

Keeping it switched on

Section titled “Keeping it switched on”
  • The History Sync Lock profile sets the app’s settings: the window’s Turn Off, Change… and Chrome switch are greyed out. Installing or removing it needs an administrator password.
  • The status file lets Family Filter for Mac warn when a Mac stops checking in.

Keep the child’s account standard and the app in /Applications.

Sending to the history service

Section titled “Sending to the history service”

With the service’s address and a token in the lock profile, each run also writes the CSVs to a local outbox and sends what the history service doesn’t have yet.

  • Offsets, not rows: each file’s new bytes go with the offset they start at, so a retry or a lost reply never duplicates anything.
  • Off the VPN, the send fails, is logged, and the next run catches up from the outbox.
  • The first send starts from the beginning, so the service gets everything still in the browsers’ history files.

Status file

Section titled “Status file”

After every check, History Sync rewrites heartbeat.json in this Mac’s folder: when it last checked, whether the check worked, the background service’s state, Full Disk Access, the Chrome lock, and whether the account is a standard user.

Files

Section titled “Files”
File What
~/Library/Application Support/safari-history/config.json Settings
~/Library/Application Support/safari-history/state.json Progress
~/Library/Application Support/safari-history/outbox/ Files waiting for the history service
~/Library/Logs/safari-history.log Log

Source: sync/README.md