homewatch 0.1.0__tar.gz

homewatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

homewatch-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: homewatch
+Version: 0.1.0
+Summary: Home counter-surveillance detector for Linux: Remote ID drones, Bluetooth trackers, unknown devices, RF.
+Author: Ryan Davis
+License: MIT
+Project-URL: Homepage, https://github.com/sloppytopp/homewatch
+Project-URL: Issues, https://github.com/sloppytopp/homewatch/issues
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.21
+Dynamic: license-file
+
+# homewatch
+Home counter-surveillance **detector** for **Linux** (BlueZ + NetworkManager + `iw`). Detect-only: no jamming, no spoofing.
+Run: `./homewatch.sh setup` once, then `./homewatch.sh run` -> http://127.0.0.1:8777
+
+![dashboard with made-up demo data](https://raw.githubusercontent.com/sloppytopp/homewatch/main/docs/screenshot.png)
+
+## Install
+`pip install homewatch` (or from source below). System packages are still needed:
+`sudo apt install ieee-data nmap iw network-manager bluez` (the vendor database from `ieee-data`/`nmap` is required for
+camera/drone vendor detection - Homewatch warns at startup if it is missing), then
+`python3 -m venv .venv --system-site-packages && .venv/bin/pip install bleak`.
+Optional RF module: `sudo apt install rtl-sdr` + an RTL-SDR dongle (24 MHz-1.7 GHz only; not 2.4/5.8 GHz).
+
+## Commands
+| Command | What |
+|---|---|
+| `setup` | first-run walkthrough: your Wi-Fi, home position, which devices are yours |
+| `run [--lan]` | all detectors + dashboard (type `b`+Enter to log a sensor beep) |
+| `scan` | one-shot scan |
+| `beep [--ago MIN]` / `report` | log sensor beeps / line them up against detections (with background baseline) |
+| `devices` / `trust all\|<mac>` | LAN inventory; the first scan auto-trusts everything - **review it** |
+| `find <BLE addr>` | hot/cold locator |
+| `home <lat> <lon>` | home position for the drone map (west longitude is negative) |
+| `ntfy setup\|test\|on\|off` | phone alerts (generic text only, via ntfy.sh) |
+| `selftest` | unit tests |
+
+## Read this first
+- **This is not a guarantee of safety.** A quiet dashboard means "nothing seen by these radios", not "nothing is there".
+  Blind spots: drones without Remote ID, SD-card-only cameras, cellular/GPS trackers, anything on 2.4/5.8 GHz video.
+- **Remote ID is unauthenticated.** Anyone can broadcast a fake one, so a red drone alert means a broadcast *claims* a
+  drone. Position and operator location are whatever the sender says. Operator coordinates are shown live and are
+  **never written to disk**; events are pruned after 30 days.
+- **Do not interfere with a drone** (shooting at, jamming or spoofing one is a federal crime). Report it to law
+  enforcement or the FAA.
+- **The radar is a rough estimate.** Signal strength gives only a crude distance, badly distorted indoors, and no direction.
+- **If you find something:** don't touch or move it, photograph it where it is, note the time, and contact local law
+  enforcement. A tracker you don't own: Apple/Android show unknown-tracker alerts and can help identify it.
+- **`--lan` is plain HTTP.** Anyone sniffing your Wi-Fi can see the private link/token. Use it only on a network you trust.
+  Localhost mode only accepts `Host: 127.0.0.1/localhost` (blocks DNS rebinding) and state-changing requests need an
+  `X-Homewatch` header.
+- Your Wi-Fi name, home position, tokens and the ntfy topic live in `~/.local/share/homewatch/config.json` (mode 600), never in the code.

homewatch-0.1.0/README.md

@@ -0,0 +1,41 @@
+# homewatch
+Home counter-surveillance **detector** for **Linux** (BlueZ + NetworkManager + `iw`). Detect-only: no jamming, no spoofing.
+Run: `./homewatch.sh setup` once, then `./homewatch.sh run` -> http://127.0.0.1:8777
+
+![dashboard with made-up demo data](https://raw.githubusercontent.com/sloppytopp/homewatch/main/docs/screenshot.png)
+
+## Install
+`pip install homewatch` (or from source below). System packages are still needed:
+`sudo apt install ieee-data nmap iw network-manager bluez` (the vendor database from `ieee-data`/`nmap` is required for
+camera/drone vendor detection - Homewatch warns at startup if it is missing), then
+`python3 -m venv .venv --system-site-packages && .venv/bin/pip install bleak`.
+Optional RF module: `sudo apt install rtl-sdr` + an RTL-SDR dongle (24 MHz-1.7 GHz only; not 2.4/5.8 GHz).
+
+## Commands
+| Command | What |
+|---|---|
+| `setup` | first-run walkthrough: your Wi-Fi, home position, which devices are yours |
+| `run [--lan]` | all detectors + dashboard (type `b`+Enter to log a sensor beep) |
+| `scan` | one-shot scan |
+| `beep [--ago MIN]` / `report` | log sensor beeps / line them up against detections (with background baseline) |
+| `devices` / `trust all\|<mac>` | LAN inventory; the first scan auto-trusts everything - **review it** |
+| `find <BLE addr>` | hot/cold locator |
+| `home <lat> <lon>` | home position for the drone map (west longitude is negative) |
+| `ntfy setup\|test\|on\|off` | phone alerts (generic text only, via ntfy.sh) |
+| `selftest` | unit tests |
+
+## Read this first
+- **This is not a guarantee of safety.** A quiet dashboard means "nothing seen by these radios", not "nothing is there".
+  Blind spots: drones without Remote ID, SD-card-only cameras, cellular/GPS trackers, anything on 2.4/5.8 GHz video.
+- **Remote ID is unauthenticated.** Anyone can broadcast a fake one, so a red drone alert means a broadcast *claims* a
+  drone. Position and operator location are whatever the sender says. Operator coordinates are shown live and are
+  **never written to disk**; events are pruned after 30 days.
+- **Do not interfere with a drone** (shooting at, jamming or spoofing one is a federal crime). Report it to law
+  enforcement or the FAA.
+- **The radar is a rough estimate.** Signal strength gives only a crude distance, badly distorted indoors, and no direction.
+- **If you find something:** don't touch or move it, photograph it where it is, note the time, and contact local law
+  enforcement. A tracker you don't own: Apple/Android show unknown-tracker alerts and can help identify it.
+- **`--lan` is plain HTTP.** Anyone sniffing your Wi-Fi can see the private link/token. Use it only on a network you trust.
+  Localhost mode only accepts `Host: 127.0.0.1/localhost` (blocks DNS rebinding) and state-changing requests need an
+  `X-Homewatch` header.
+- Your Wi-Fi name, home position, tokens and the ntfy topic live in `~/.local/share/homewatch/config.json` (mode 600), never in the code.

homewatch-0.1.0/homewatch/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

homewatch-0.1.0/homewatch/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()

homewatch-0.1.0/homewatch/cli.py

@@ -0,0 +1,314 @@
+import argparse
+import sys
+import threading
+import time
+
+from .core import DOMAINS, DB, Engine, load_config, save_config, new_token
+
+ICON = {"ok": "OK   ", "watch": "WATCH", "alert": "ALERT", "off": "off  "}
+
+
+def cmd_run(a):
+    from . import det_ble, det_host, det_lan, det_sdr, det_wifi, web
+    eng = Engine()
+    det_ble.BLEDetector(eng).start()
+    if not a.no_wifi:
+        det_wifi.WifiDetector(eng).start()
+        det_lan.LanDetector(eng).start()
+    det_host.HostDetector(eng, own_port=a.port).start()
+    det_sdr.SdrDetector(eng).start()
+    from . import oui
+    if oui.table_size() == 0:
+        print("WARNING: no MAC vendor database found - camera/drone vendor detection is OFF.\n"
+              "         Install it:  sudo apt install ieee-data nmap", flush=True)
+    eng.db.prune()
+    cfg = load_config()
+    if not cfg.get("my_ssids"):  # learn which Wi-Fi is yours (first run) - never hardcoded
+        import subprocess
+        out = subprocess.run(["nmcli", "-t", "-f", "active,ssid", "dev", "wifi"], capture_output=True, text=True).stdout
+        mine = sorted({l.split(":", 1)[1] for l in out.splitlines() if l.startswith("yes:") and l.split(":", 1)[1]})
+        if mine:
+            cfg["my_ssids"] = mine
+            save_config(cfg)
+            print(f"Learned your Wi-Fi name(s): {', '.join(mine)}  (edit my_ssids in {__import__('homewatch.core', fromlist=['x']).CONFIG_PATH})")
+    token = None
+    if a.lan:
+        token = cfg.setdefault("dashboard_key", new_token())
+        save_config(cfg)
+    web.serve(eng, "0.0.0.0" if a.lan else "127.0.0.1", a.port, token)
+    print(f"Homewatch running. Dashboard: http://127.0.0.1:{a.port}")
+    if a.lan:
+        import subprocess
+        ip = subprocess.run("hostname -I", shell=True, capture_output=True, text=True).stdout.split()[0]
+        print(f"Phone (same Wi-Fi): http://{ip}:{a.port}/?k={token}   <- keep this link private")
+    if a.lan:
+        print("NOTE: --lan is plain HTTP. Anyone sniffing your Wi-Fi could see the link/token. Use only on a network you trust.")
+    print(f"Phone alerts: {'ON' if cfg.get('ntfy', {}).get('enabled') else 'off (see: homewatch ntfy setup)'}\n"
+          "Type  b + Enter  when the sensor beeps.  Ctrl-C to stop.", flush=True)
+
+    def keys():
+        for line in sys.stdin:
+            if line.strip().lower() in ("b", "beep"):
+                eng.beep("keyboard")
+                print("  -> beep logged", flush=True)
+    if sys.stdin.isatty():
+        threading.Thread(target=keys, daemon=True).start()
+    try:
+        while True:
+            time.sleep(60)
+            line = " | ".join(f"{d}:{eng.state[d]['level']}" for d in DOMAINS)
+            print(f"[{time.strftime('%H:%M')}] {line}", flush=True)
+    except KeyboardInterrupt:
+        eng.stop.set()
+
+
+def cmd_beep(a):
+    db = DB()
+    ts = time.time() - a.ago * 60
+    db.exec("INSERT INTO beeps(ts,note) VALUES(?,?)", (ts, " ".join(a.note)))
+    print(f"Beep logged at {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(ts))}")
+
+
+def cmd_report(a):
+    db = DB()
+    since = time.time() - a.hours * 3600
+    beeps = db.query("SELECT * FROM beeps WHERE ts>? ORDER BY ts", (since,))
+    if not beeps:
+        print("No beeps logged in that window. Log them with: homewatch beep   (or 'b' in `run`)")
+    hits = 0
+    for b in beeps:
+        near = db.query("SELECT * FROM events WHERE ts BETWEEN ? AND ? AND level IN ('alert','watch') "
+                        "AND kind!='beep' ORDER BY ts", (b["ts"] - a.window * 60, b["ts"] + a.window * 60))
+        stamp = time.strftime("%a %m-%d %H:%M:%S", time.localtime(b["ts"]))
+        print(f"\nBEEP {stamp}  {b['note'] or ''}")
+        if near:
+            hits += 1
+            for e in near:
+                print(f"   {time.strftime('%H:%M:%S', time.localtime(e['ts']))} {e['level']:5} {e['domain']:7} {e['msg']}")
+        else:
+            print(f"   nothing flagged within +/-{a.window} min")
+    if beeps:
+        print(f"\n== {hits}/{len(beeps)} beeps had a detection nearby. ==")
+        hrs = sorted(time.localtime(b['ts']).tm_hour for b in beeps)
+        print("Beep hours:", ", ".join(f"{h:02d}:xx" for h in hrs))
+        if hits == 0:
+            print("No drone, tracker, camera or RF event lines up with any beep -> sensor/animal/environment is the likely cause.")
+    if beeps:
+        span = max(1.0, (time.time() - min(since, beeps[0]["ts"])) / 60)
+        wins = max(1, int(span / (2 * a.window)))
+        busy = db.query("SELECT COUNT(DISTINCT CAST(ts/? AS INT)) n FROM events WHERE level IN ('alert','watch') "
+                        "AND kind!='beep' AND ts>?", (a.window * 120, since))[0]["n"]
+        print(f"Baseline: detections were present in {busy} of ~{wins} {2*a.window:.0f}-minute windows overall. "
+              f"If that is close to {hits}/{len(beeps)}, the detections are background and prove nothing about the beeps.")
+    allev = db.query("SELECT level,COUNT(*) n FROM events WHERE ts>? GROUP BY level", (since,))
+    print("Events in window:", {e["level"]: e["n"] for e in allev})
+
+
+def cmd_devices(a):
+    rows = DB().query("SELECT * FROM devices ORDER BY trusted, klass DESC, ip")
+    for d in rows:
+        t = "trusted " if d["trusted"] else "UNREVIEWED"
+        print(f"{t} {d['ip']:15} {d['mac']} {d['klass']:8} {d['vendor'][:34]:34} ports:{d['ports'] or '-'}")
+    print("\nMark yours as trusted:  homewatch trust all   |   homewatch trust <mac>")
+
+
+def cmd_trust(a):
+    db = DB()
+    if a.mac == "all":
+        db.exec("UPDATE devices SET trusted=1")
+    else:
+        db.exec("UPDATE devices SET trusted=1 WHERE mac=?", (a.mac.lower(),))
+    print("ok")
+
+
+def cmd_ignore(a):
+    db = DB()
+    cur = set(db.kv_get("ble_ignore", []))
+    cur.add(a.addr.upper())
+    db.kv_set("ble_ignore", sorted(cur))
+    print("Ignoring BLE device", a.addr, "(note: AirTags rotate addresses; this only mutes this one address)")
+
+
+def cmd_find(a):
+    import asyncio
+    from bleak import BleakScanner
+    target = a.addr.upper()
+    print(f"Hot/cold finder for {target}. Walk around; stronger bar = closer. Ctrl-C to stop.")
+
+    def cb(dev, adv):
+        if dev.address.upper() == target:
+            n = max(0, min(40, int((adv.rssi + 100) * 40 / 60)))
+            print(f"{adv.rssi:4} dBm |{'#' * n}", flush=True)
+
+    async def go():
+        async with BleakScanner(cb):
+            while True:
+                await asyncio.sleep(1)
+    try:
+        asyncio.run(go())
+    except KeyboardInterrupt:
+        pass
+
+
+def cmd_home(a):
+    cfg = load_config()
+    if a.lat is not None:
+        cfg["home"] = {"lat": a.lat, "lon": a.lon}
+        save_config(cfg)
+    print("Home location:", cfg.get("home") or "not set",
+          "\nTip: for exact position, long-press your house in Google/Apple Maps and copy the two numbers, then:"
+          "\n  homewatch home <lat> <lon>")
+
+
+def cmd_ntfy(a):
+    import urllib.request
+    cfg = load_config()
+    n = cfg.setdefault("ntfy", {})
+    if a.action == "setup":
+        n["topic"] = n.get("topic") or "homewatch-" + new_token()
+        n.setdefault("enabled", False)
+        save_config(cfg)
+        print(f"Topic created: {n['topic']}\n"
+              "1. Install the free 'ntfy' app (iOS App Store / Android Play Store).\n"
+              f"2. In the app tap + and subscribe to topic:  {n['topic']}   (server: ntfy.sh)\n"
+              "3. Then run:  homewatch ntfy test   (sends one test message)\n"
+              "4. Then run:  homewatch ntfy on\n"
+              "Note: the topic name is the only 'password', so keep it private. Pushes are generic - never MACs or coordinates.")
+        return
+    if not n.get("topic"):
+        sys.exit("Run first:  homewatch ntfy setup")
+    if a.action in ("on", "off"):
+        n["enabled"] = a.action == "on"
+        save_config(cfg)
+        print("Phone alerts", "ON" if n["enabled"] else "OFF")
+    elif a.action == "test":
+        req = urllib.request.Request(f"https://ntfy.sh/{n['topic']}", data=b"Homewatch test: phone alerts work.",
+                                     headers={"Title": "Homewatch"}, method="POST")
+        urllib.request.urlopen(req, timeout=10).read()
+        print("Test message sent. Check your phone.")
+
+
+def cmd_setup(a):
+    """First-run walkthrough: your Wi-Fi, home position, and which devices on the network are yours."""
+    import socket
+    import subprocess
+    from . import det_lan
+    cfg = load_config()
+    print("Homewatch setup - takes about a minute.\n")
+    out = subprocess.run(["nmcli", "-t", "-f", "active,ssid", "dev", "wifi"], capture_output=True, text=True).stdout
+    mine = sorted({l.split(":", 1)[1] for l in out.splitlines() if l.startswith("yes:") and l.split(":", 1)[1]})
+    if mine:
+        ok = input(f"1. Is your home Wi-Fi '{', '.join(mine)}'? [Y/n] ").strip().lower() != "n"
+        if ok:
+            cfg["my_ssids"] = mine
+    if "home" not in cfg:
+        print("\n2. Home position (optional, for the drone map). In Google/Apple Maps long-press your house and copy the")
+        print("   two numbers. West longitude is negative (e.g. 40.7128 -74.0060). Press Enter to skip.")
+        raw = input("   lat lon: ").split()
+        if len(raw) == 2:
+            try:
+                cfg["home"] = {"lat": float(raw[0]), "lon": float(raw[1])}
+            except ValueError:
+                print("   (couldn't read that - skipped)")
+    save_config(cfg)
+    print("\n3. Scanning your network for devices...")
+    eng = Engine(quiet=True)
+    det_lan.LanDetector(eng).scan()
+    pend = eng.db.query("SELECT * FROM devices WHERE trusted=0 ORDER BY ip")
+    if not pend:
+        print("   Nothing to review.")
+    for d in pend:
+        try:
+            name = socket.gethostbyaddr(d["ip"])[0]
+        except OSError:
+            name = ""
+        what = f"{d['ip']:15} {d['mac']}  {d['vendor']}  {name}".rstrip()
+        ans = input(f"   Is this yours?  {what}  [y/N/a=all remaining] ").strip().lower()
+        if ans == "a":
+            eng.db.exec("UPDATE devices SET trusted=1 WHERE trusted=0")
+            break
+        if ans == "y":
+            eng.db.exec("UPDATE devices SET trusted=1 WHERE mac=?", (d["mac"],))
+    left = eng.db.query("SELECT COUNT(*) n FROM devices WHERE trusted=0")[0]["n"]
+    print(f"\nDone. {left} device(s) left unreviewed - they will show amber until you identify them "
+          "(your router's client list can help).\nStart with:  homewatch run")
+
+
+def cmd_scan(a):
+    """One-shot scan of everything, print answers, exit."""
+    from . import det_ble, det_host, det_lan, det_wifi
+    eng = Engine(quiet=True)
+    ble = det_ble.BLEDetector(eng)
+    ble.start()
+    print("Scanning ~25s (Bluetooth + Wi-Fi + LAN + this computer)...", flush=True)
+    wd = det_wifi.WifiDetector(eng)
+    try:
+        wd.evaluate(wd.scan())
+    except Exception as e:
+        eng.status("drone", "watch", f"Wi-Fi: {e}", "wifi")
+    try:
+        det_lan.LanDetector(eng).scan()
+    except Exception as e:
+        eng.status("network", "watch", f"LAN: {e}", "lan")
+    try:
+        det_host.HostDetector(eng).check()
+    except Exception as e:
+        eng.status("host", "watch", str(e))
+    from . import det_sdr
+    det_sdr.SdrDetector(eng).start()
+    time.sleep(20)
+    ble._evaluate()
+    eng.stop.set()
+    for d, t in DOMAINS.items():
+        s = eng.state[d]
+        print(f"{ICON[s['level']]}  {t}\n         {s['msg']}")
+
+
+def cmd_selftest(a):
+    import os
+    import unittest
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    if not os.path.isdir(os.path.join(root, "tests")):
+        sys.exit("selftest needs a source checkout (tests/ not found).")
+    os.chdir(root)
+    sys.exit(unittest.main(module=None, argv=["x", "discover", "-s", "tests", "-t", "."]))
+
+
+def main():
+    p = argparse.ArgumentParser(prog="homewatch", description="Home counter-surveillance detector")
+    sp = p.add_subparsers(dest="cmd", required=True)
+    r = sp.add_parser("run", help="run all detectors + dashboard")
+    r.add_argument("--lan", action="store_true", help="serve dashboard to phones on your LAN")
+    r.add_argument("--port", type=int, default=8777)
+    r.add_argument("--no-wifi", action="store_true")
+    r.set_defaults(f=cmd_run)
+    b = sp.add_parser("beep", help="log that the sensor just beeped")
+    b.add_argument("--ago", type=float, default=0, help="minutes ago")
+    b.add_argument("note", nargs="*")
+    b.set_defaults(f=cmd_beep)
+    rp = sp.add_parser("report", help="line up beeps against detections")
+    rp.add_argument("--hours", type=float, default=72)
+    rp.add_argument("--window", type=float, default=5, help="minutes either side of a beep")
+    rp.set_defaults(f=cmd_report)
+    sp.add_parser("devices", help="LAN inventory").set_defaults(f=cmd_devices)
+    t = sp.add_parser("trust", help="mark LAN device(s) as yours")
+    t.add_argument("mac")
+    t.set_defaults(f=cmd_trust)
+    i = sp.add_parser("ignore", help="mute a BLE address (your own tracker)")
+    i.add_argument("addr")
+    i.set_defaults(f=cmd_ignore)
+    f = sp.add_parser("find", help="hot/cold locator for a BLE device")
+    f.add_argument("addr")
+    f.set_defaults(f=cmd_find)
+    h = sp.add_parser("home", help="show/set home lat lon for the drone map")
+    h.add_argument("lat", type=float, nargs="?")
+    h.add_argument("lon", type=float, nargs="?")
+    h.set_defaults(f=cmd_home)
+    nt = sp.add_parser("ntfy", help="phone alerts via ntfy.sh")
+    nt.add_argument("action", choices=["setup", "test", "on", "off"])
+    nt.set_defaults(f=cmd_ntfy)
+    sp.add_parser("setup", help="first-run walkthrough").set_defaults(f=cmd_setup)
+    sp.add_parser("scan", help="one-shot scan, print answers").set_defaults(f=cmd_scan)
+    sp.add_parser("selftest").set_defaults(f=cmd_selftest)
+    a = p.parse_args()
+    a.f(a)

homewatch-0.1.0/homewatch/core.py

@@ -0,0 +1,174 @@
+"""Shared engine: sqlite log, live status per question, alerts."""
+import json
+import os
+import secrets
+import urllib.request
+import shutil
+import sqlite3
+import subprocess
+import threading
+import time
+
+DATA_DIR = os.environ.get("HOMEWATCH_DIR") or os.path.expanduser("~/.local/share/homewatch")
+DOMAINS = {
+    "drone": "Drone near the house?",
+    "tracker": "Active tracker present?",
+    "network": "Hidden camera / unknown device?",
+    "rf": "Elevated RF / EMF? (RTL-SDR)",
+    "host": "This computer's own camera/mic/remote access",
+}
+LEVELS = ("off", "ok", "watch", "alert")
+
+CONFIG_PATH = os.path.join(DATA_DIR, "config.json")
+PUSH_TEXT = {  # phone pushes are deliberately generic: no MACs, no coordinates
+    "drone": "A drone signal was detected near the house.",
+    "tracker": "A tracker has stayed close to the house.",
+    "network": "Something new or camera-like showed up on your network.",
+    "rf": "Unusual radio activity was detected.",
+    "host": "Your computer's camera, mic or remote access triggered.",
+}
+
+
+def load_config():
+    try:
+        with open(CONFIG_PATH) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {}
+
+
+def save_config(cfg):
+    os.makedirs(DATA_DIR, exist_ok=True)
+    with open(CONFIG_PATH, "w") as f:
+        json.dump(cfg, f, indent=2)
+    os.chmod(CONFIG_PATH, 0o600)
+
+
+def new_token():
+    return secrets.token_urlsafe(9)
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS events(id INTEGER PRIMARY KEY, ts REAL, domain TEXT,
+  level TEXT, kind TEXT, key TEXT, msg TEXT, detail TEXT);
+CREATE INDEX IF NOT EXISTS ev_ts ON events(ts);
+CREATE TABLE IF NOT EXISTS beeps(id INTEGER PRIMARY KEY, ts REAL, note TEXT);
+CREATE TABLE IF NOT EXISTS devices(mac TEXT PRIMARY KEY, first_seen REAL, last_seen REAL,
+  ip TEXT, vendor TEXT, klass TEXT, ports TEXT, trusted INTEGER DEFAULT 0);
+CREATE TABLE IF NOT EXISTS kv(k TEXT PRIMARY KEY, v TEXT);
+"""
+
+
+class DB:
+    def __init__(self, path=None):
+        os.makedirs(DATA_DIR, exist_ok=True)
+        self.path = path or os.path.join(DATA_DIR, "homewatch.db")
+        self.c = sqlite3.connect(self.path, check_same_thread=False)
+        self.c.row_factory = sqlite3.Row
+        self.lock = threading.Lock()
+        with self.lock:
+            self.c.executescript(SCHEMA)
+
+    def exec(self, sql, args=()):
+        with self.lock:
+            cur = self.c.execute(sql, args)
+            self.c.commit()
+            return cur
+
+    def query(self, sql, args=()):
+        with self.lock:
+            return [dict(r) for r in self.c.execute(sql, args).fetchall()]
+
+    def prune(self, days=30):
+        """Retention: don't keep sighting history forever."""
+        self.exec("DELETE FROM events WHERE ts < ?", (time.time() - days * 86400,))
+        self.exec("DELETE FROM beeps WHERE ts < ?", (time.time() - 365 * 86400,))
+
+    def kv_get(self, k, default=None):
+        r = self.query("SELECT v FROM kv WHERE k=?", (k,))
+        return json.loads(r[0]["v"]) if r else default
+
+    def kv_set(self, k, v):
+        self.exec("INSERT OR REPLACE INTO kv(k,v) VALUES(?,?)", (k, json.dumps(v)))
+
+
+class Engine:
+    def __init__(self, db=None, quiet=False):
+        self.db = db or DB()
+        self.quiet = quiet
+        self.state = {d: {"level": "off", "msg": "starting", "ts": time.time()} for d in DOMAINS}
+        self.lock = threading.Lock()
+        self.sources = {}
+        self.stop = threading.Event()
+        self._last_emit = {}
+        self.live = {}  # free-form live detail per detector (shown on dashboard)
+        self._last_push = {}
+
+    # -- status -------------------------------------------------------
+    def status(self, domain, level, msg, source="main"):
+        """Each source reports its own level; the domain shows the worst one."""
+        with self.lock:
+            prev = self.state[domain]["level"]
+            self.sources.setdefault(domain, {})[source] = (level, msg, time.time())
+            worst = max(self.sources[domain].values(), key=lambda v: LEVELS.index(v[0]))
+            self.state[domain] = {"level": worst[0], "msg": worst[1], "ts": time.time()}
+            cur = worst[0]
+        if cur == "alert" and prev != "alert":
+            self.notify(f"HOMEWATCH ALERT: {DOMAINS[domain]}", worst[1], push=PUSH_TEXT.get(domain))
+
+    # -- events -------------------------------------------------------
+    def emit(self, domain, level, kind, key, msg, detail=None, cooldown=600):
+        now = time.time()
+        k = (kind, key)
+        if now - self._last_emit.get(k, 0) < cooldown:
+            return False
+        self._last_emit[k] = now
+        self.db.exec(
+            "INSERT INTO events(ts,domain,level,kind,key,msg,detail) VALUES(?,?,?,?,?,?,?)",
+            (now, domain, level, kind, key, msg, json.dumps(detail or {}, default=str)),
+        )
+        if not self.quiet:
+            stamp = time.strftime("%H:%M:%S", time.localtime(now))
+            print(f"[{stamp}] {level.upper():5} {domain:7} {msg}", flush=True)
+        return True
+
+    def beep(self, note="", ts=None):
+        self.db.exec("INSERT INTO beeps(ts,note) VALUES(?,?)", (ts or time.time(), note))
+
+    # -- alerting -----------------------------------------------------
+    def push(self, text, title="Homewatch"):
+        """Phone alert via ntfy.sh. Off until `homewatch ntfy on`. Never includes MACs/coordinates."""
+        cfg = load_config().get("ntfy", {})
+        if self.quiet or not (cfg.get("enabled") and cfg.get("topic")):
+            return False
+        now = time.time()
+        if now - self._last_push.get(text, 0) < 120:
+            return False
+        self._last_push[text] = now
+        try:
+            req = urllib.request.Request(f"https://ntfy.sh/{cfg['topic']}", data=text.encode(),
+                                         headers={"Title": title, "Tags": "satellite"}, method="POST")
+            urllib.request.urlopen(req, timeout=8).read()
+            return True
+        except Exception:
+            return False
+
+    def notify(self, title, body, push=None):
+        if self.quiet:
+            return
+        if push:
+            threading.Thread(target=self.push, args=(push,), daemon=True).start()
+        # Soft chime only - no voice. Set HOMEWATCH_SOUND=off to silence completely.
+        if os.environ.get("HOMEWATCH_SOUND", "ding") != "off" and shutil.which("paplay"):
+            snd = "/usr/share/sounds/freedesktop/stereo/message.oga"
+            subprocess.Popen(["paplay", snd], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        if shutil.which("notify-send"):
+            subprocess.Popen(["notify-send", "-u", "normal", title, body],
+                             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+    def snapshot(self):
+        with self.lock:
+            st = {d: dict(v, title=DOMAINS[d]) for d, v in self.state.items()}
+        recent = self.db.query("SELECT ts,domain,level,msg FROM events ORDER BY id DESC LIMIT 40")
+        return {"now": time.time(), "state": st, "events": recent, "live": self.live,
+                "home": load_config().get("home"), "my_ssids": load_config().get("my_ssids", [])}