Add LAN device discovery (ping sweep + ARP, known/unknown labeling)

Runs as a host-level systemd timer on CT122 (scripts/discover-devices.sh)
rather than inside the api container, since real ARP entries live in the
host's network namespace, not Docker's bridge network. See
docs/device-discovery.md for the full writeup, including why literal
passive-only ARP reading was dropped (near-empty result in practice).

API reads the resulting JSON file each poll cycle, cross-references
config/hosts.yaml's knownDevices list by IP, and serves /api/devices.
Dashboard gets a new "Network Devices" table.

Closes #9.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/api/src/config/index.ts

@@ -12,12 +12,18 @@ interface RawSshHost {
   diskPaths?: { path: string; label: string }[];
 }
 
+interface RawKnownDevice {
+  ip: string;
+  name: string;
+}
+
 export interface HostsConfig {
   proxmox: {
     host: string;
     node: string;
   };
   sshHosts?: RawSshHost[];
+  knownDevices?: RawKnownDevice[];
 }
 
 export interface AppConfig {
@@ -39,6 +45,8 @@ export interface AppConfig {
     tokenSecret: string;
   };
   sshHosts: SshHostConfig[];
+  knownDevices: Map<string, string>;
+  discoveryFilePath: string;
   hosts: HostsConfig;
 }
 
@@ -80,6 +88,8 @@ export function loadConfig(hostsConfigPath: string): AppConfig {
       tokenSecret: required("PROXMOX_TOKEN_SECRET"),
     },
     sshHosts,
+    knownDevices: new Map((hosts.knownDevices ?? []).map((d) => [d.ip, d.name])),
+    discoveryFilePath: process.env.DISCOVERY_FILE_PATH ?? "./data/devices-raw.json",
     hosts,
   };
 }

apps/api/src/db/index.ts

@@ -36,6 +36,14 @@ export function openDb(path: string): Database.Database {
     );
 
     CREATE INDEX IF NOT EXISTS idx_snapshots_host_ts ON metric_snapshots(host_id, ts);
+
+    CREATE TABLE IF NOT EXISTS devices (
+      ip TEXT PRIMARY KEY,
+      mac TEXT NOT NULL,
+      known_name TEXT,
+      first_seen TEXT NOT NULL DEFAULT (datetime('now')),
+      last_seen TEXT NOT NULL DEFAULT (datetime('now'))
+    );
   `);
   return db;
 }
@@ -100,3 +108,45 @@ export function pruneOldSnapshots(db: Database.Database, retentionHours: number)
     cutoff: `-${retentionHours} hours`,
   });
 }
+
+export interface DiscoveredDevice {
+  ip: string;
+  mac: string;
+  knownName: string | null;
+}
+
+export function upsertDevices(db: Database.Database, devices: DiscoveredDevice[]): void {
+  const upsert = db.prepare(`
+    INSERT INTO devices (ip, mac, known_name)
+    VALUES (@ip, @mac, @knownName)
+    ON CONFLICT(ip) DO UPDATE SET
+      mac = excluded.mac,
+      known_name = excluded.known_name,
+      last_seen = datetime('now')
+  `);
+  const tx = db.transaction((items: DiscoveredDevice[]) => {
+    for (const d of items) upsert.run(d);
+  });
+  tx(devices);
+}
+
+export interface DeviceRow {
+  ip: string;
+  mac: string;
+  known_name: string | null;
+  first_seen: string;
+  last_seen: string;
+}
+
+// Devices not seen in the last 24h (unplugged, moved, DHCP lease expired) are
+// dropped from the list rather than shown as permanently "known but offline" —
+// there's no persistent per-device up/down state to track like hosts have.
+export function getRecentDevices(db: Database.Database, sinceHours = 24): DeviceRow[] {
+  return db
+    .prepare(
+      `SELECT ip, mac, known_name, first_seen, last_seen FROM devices
+       WHERE last_seen > datetime('now', @cutoff)
+       ORDER BY known_name IS NULL, ip`
+    )
+    .all({ cutoff: `-${sinceHours} hours` }) as DeviceRow[];
+}

apps/api/src/discovery/index.ts

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import type Database from "better-sqlite3";
+import { upsertDevices, type DiscoveredDevice } from "../db/index.js";
+
+interface RawEntry {
+  ip: string;
+  mac: string;
+  state: string;
+}
+
+// Reads the JSON file produced by scripts/discover-devices.sh (a systemd timer
+// on the deploy host, not this process) and labels each entry against the
+// known-device list from config/hosts.yaml. See docs/device-discovery.md.
+export async function refreshDevices(
+  db: Database.Database,
+  filePath: string,
+  knownDevices: Map<string, string>
+): Promise<void> {
+  let raw: RawEntry[];
+  try {
+    raw = JSON.parse(await readFile(filePath, "utf8"));
+  } catch (err) {
+    // Missing file (timer hasn't run yet, or not deployed on this host) isn't
+    // fatal — just means no device data this cycle.
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw err;
+  }
+
+  const devices: DiscoveredDevice[] = raw.map((entry) => ({
+    ip: entry.ip,
+    mac: entry.mac,
+    knownName: knownDevices.get(entry.ip) ?? null,
+  }));
+
+  upsertDevices(db, devices);
+}

apps/api/src/index.ts

@@ -10,6 +10,8 @@ import { SshHostCollector } from "./collectors/sshHost.js";
 import type { Collector } from "./collectors/types.js";
 import { registerAuthRoutes } from "./routes/auth.js";
 import { registerHostRoutes } from "./routes/hosts.js";
+import { registerDeviceRoutes } from "./routes/devices.js";
+import { refreshDevices } from "./discovery/index.js";
 
 const HOSTS_CONFIG_PATH = process.env.HOSTS_CONFIG_PATH ?? "../../config/hosts.yaml";
 
@@ -41,6 +43,12 @@ async function main() {
       }
     }
     pruneOldSnapshots(db, cfg.snapshotRetentionHours);
+
+    try {
+      await refreshDevices(db, cfg.discoveryFilePath, cfg.knownDevices);
+    } catch (err) {
+      app.log.error({ err }, "device discovery refresh failed");
+    }
   }
 
   const app = Fastify({ logger: true });
@@ -53,6 +61,7 @@ async function main() {
 
   registerAuthRoutes(app, db);
   registerHostRoutes(app, db);
+  registerDeviceRoutes(app, db);
 
   await pollOnce();
   setInterval(() => {

apps/api/src/routes/devices.ts

@@ -0,0 +1,25 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import type Database from "better-sqlite3";
+import { getRecentDevices } from "../db/index.js";
+
+async function requireAuth(req: FastifyRequest, reply: FastifyReply) {
+  if (!req.session.username) {
+    reply.code(401).send({ error: "not authenticated" });
+  }
+}
+
+export function registerDeviceRoutes(app: FastifyInstance, db: Database.Database): void {
+  app.get("/api/devices", { preHandler: requireAuth }, async () => {
+    const rows = getRecentDevices(db);
+    return {
+      devices: rows.map((r) => ({
+        ip: r.ip,
+        mac: r.mac,
+        name: r.known_name,
+        known: r.known_name !== null,
+        firstSeen: r.first_seen,
+        lastSeen: r.last_seen,
+      })),
+    };
+  });
+}