Add device-certificate mTLS auth, live position tracking, and API docs

Introduces a CA/PKI module so field devices can authenticate to Mosquitto
over TLS (8883) with per-device client certificates (CN = serial number)
instead of a shared password, with matching Devices/MQTT-Certs UI. Adds
live transmitter position tracking alongside logged points, an MQTTS
transport option in the simulator for exercising the real cert-auth path,
and Swagger API docs at /api/docs.

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

web/pages/settings/devices.tsx

@@ -1,7 +1,11 @@
-import { FormEvent, useCallback, useEffect, useState } from 'react';
+import { Fragment, FormEvent, useCallback, useEffect, useState } from 'react';
 import Layout from '../../components/Layout';
+import JobMap from '../../components/map/JobMap';
+import type { MapPoint } from '../../components/map/types';
 import { api } from '../../lib/api';
 import { useRequireAuth } from '../../lib/auth-context';
+import { useDevicesStream } from '../../lib/use-devices-stream';
+import { formatRelativeTime } from '../../lib/format';
 
 interface DeviceRow {
   id: string;
@@ -13,6 +17,35 @@ interface DeviceRow {
   lastSeenAt: string | null;
 }
 
+interface LocationResult {
+  point: MapPoint | null;
+  job: { id: string; ticketNumber: string; title: string } | null;
+}
+
+interface CertInfo {
+  id: string;
+  serialNumber: string;
+  commonName: string;
+  fingerprint: string;
+  issuedAt: string;
+  expiresAt: string;
+}
+
+async function downloadText(path: string, filename: string) {
+  const res = await fetch(path);
+  if (!res.ok) {
+    throw new Error(`Download failed (${res.status})`);
+  }
+  const text = await res.text();
+  const blob = new Blob([text], { type: 'application/x-pem-file' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
 export default function DevicesPage() {
   const { user, activeOrg, loading } = useRequireAuth();
   const orgId = activeOrg?.org.id ?? null;
@@ -25,6 +58,22 @@ export default function DevicesPage() {
   const [notice, setNotice] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
+  const [locationDeviceId, setLocationDeviceId] = useState<string | null>(null);
+  const [locationResult, setLocationResult] = useState<LocationResult | null>(null);
+  const [locationLoading, setLocationLoading] = useState(false);
+
+  const [certDeviceId, setCertDeviceId] = useState<string | null>(null);
+  const [certInfo, setCertInfo] = useState<CertInfo | null>(null);
+  const [certLoading, setCertLoading] = useState(false);
+  const [certBusy, setCertBusy] = useState(false);
+
+  // Forces "last contact" strings to re-render periodically without refetching devices.
+  const [, setTick] = useState(0);
+  useEffect(() => {
+    const timer = setInterval(() => setTick((t) => t + 1), 30_000);
+    return () => clearInterval(timer);
+  }, []);
+
   const reload = useCallback(() => {
     if (!orgId) {
       return;
@@ -40,6 +89,24 @@ export default function DevicesPage() {
 
   useEffect(reload, [reload]);
 
+  useDevicesStream(orgId, (evt) => {
+    setDevices((rows) =>
+      rows.map((d) =>
+        d.id === evt.deviceId
+          ? {
+              ...d,
+              lastSeenAt: evt.lastSeenAt ?? d.lastSeenAt,
+              isActive: evt.isActive ?? d.isActive,
+              disabledReason: evt.isActive !== undefined ? evt.disabledReason ?? null : d.disabledReason,
+            }
+          : d,
+      ),
+    );
+    if (evt.position && evt.deviceId === locationDeviceId) {
+      setLocationResult({ point: evt.position, job: evt.job ?? null });
+    }
+  });
+
   const addDevice = async (e: FormEvent) => {
     e.preventDefault();
     try {
@@ -95,10 +162,77 @@ export default function DevicesPage() {
     }
   };
 
+  const toggleLocation = async (deviceId: string) => {
+    if (locationDeviceId === deviceId) {
+      setLocationDeviceId(null);
+      setLocationResult(null);
+      return;
+    }
+    setLocationDeviceId(deviceId);
+    setLocationResult(null);
+    setLocationLoading(true);
+    try {
+      const result = await api.get<LocationResult>(`/api/orgs/${orgId}/devices/${deviceId}/location`);
+      setLocationResult(result);
+    } catch (err: any) {
+      setError(err.message);
+    } finally {
+      setLocationLoading(false);
+    }
+  };
+
+  const toggleCert = async (deviceId: string) => {
+    if (certDeviceId === deviceId) {
+      setCertDeviceId(null);
+      setCertInfo(null);
+      return;
+    }
+    setCertDeviceId(deviceId);
+    setCertInfo(null);
+    setCertLoading(true);
+    try {
+      const result = await api.get<CertInfo>(`/api/orgs/${orgId}/devices/${deviceId}/certificate`);
+      setCertInfo(result);
+    } catch (err: any) {
+      if (err.status !== 404) {
+        setError(err.message);
+      }
+      setCertInfo(null);
+    } finally {
+      setCertLoading(false);
+    }
+  };
+
+  const issueCert = async (deviceId: string) => {
+    setCertBusy(true);
+    try {
+      const result = await api.post<CertInfo>(`/api/orgs/${orgId}/devices/${deviceId}/certificate`, {});
+      setCertInfo(result);
+    } catch (err: any) {
+      setError(err.message);
+    } finally {
+      setCertBusy(false);
+    }
+  };
+
+  const revokeCert = async (deviceId: string) => {
+    setCertBusy(true);
+    try {
+      await api.delete(`/api/orgs/${orgId}/devices/${deviceId}/certificate`);
+      setCertInfo(null);
+    } catch (err: any) {
+      setError(err.message);
+    } finally {
+      setCertBusy(false);
+    }
+  };
+
   if (loading || !user) {
     return null;
   }
 
+  const columnCount = isAdmin ? 8 : 7;
+
   return (
     <Layout title="Devices">
       <h1>Devices</h1>
@@ -142,40 +276,110 @@ export default function DevicesPage() {
             <th>MQTT username</th>
             <th>Serial</th>
             <th>Status</th>
-            <th>Last seen</th>
+            <th>Last contact</th>
+            <th>Location</th>
+            <th>Certificate</th>
             {isAdmin && <th />}
           </tr>
         </thead>
         <tbody>
           {devices.map((d) => (
-            <tr key={d.id} style={{ borderBottom: '1px solid #eee' }}>
-              <td style={{ padding: '0.5rem' }}>{d.name}</td>
-              <td>{d.mqttUsername ? <code>{d.mqttUsername}</code> : '—'}</td>
-              <td>{d.serialNumber ?? '—'}</td>
-              <td style={{ color: d.isActive ? '#388e3c' : '#c62828' }}>
-                {d.isActive ? 'active' : 'disabled'}
-                {!d.isActive && d.disabledReason && (
-                  <div style={{ color: '#888', fontWeight: 400, fontSize: '0.85rem' }}>{d.disabledReason}</div>
-                )}
-              </td>
-              <td>{d.lastSeenAt ? new Date(d.lastSeenAt).toLocaleString() : 'never'}</td>
-              {isAdmin && (
-                <td style={{ textAlign: 'right', whiteSpace: 'nowrap' }}>
-                  {d.isActive ? (
-                    <button onClick={() => setDisablingId(d.id)}>Disable</button>
-                  ) : (
-                    <button onClick={() => enable(d.id)}>Enable</button>
-                  )}{' '}
-                  <button onClick={() => remove(d.id)}>Delete</button>
+            <Fragment key={d.id}>
+              <tr style={{ borderBottom: '1px solid #eee' }}>
+                <td style={{ padding: '0.5rem' }}>{d.name}</td>
+                <td>{d.mqttUsername ? <code>{d.mqttUsername}</code> : '—'}</td>
+                <td>{d.serialNumber ?? '—'}</td>
+                <td style={{ color: d.isActive ? '#388e3c' : '#c62828' }}>
+                  {d.isActive ? 'active' : 'disabled'}
+                  {!d.isActive && d.disabledReason && (
+                    <div style={{ color: '#888', fontWeight: 400, fontSize: '0.85rem' }}>{d.disabledReason}</div>
+                  )}
                 </td>
+                <td>{formatRelativeTime(d.lastSeenAt)}</td>
+                <td>
+                  <button onClick={() => toggleLocation(d.id)}>
+                    {locationDeviceId === d.id ? 'Hide' : 'Location'}
+                  </button>
+                </td>
+                <td>
+                  <button onClick={() => toggleCert(d.id)}>{certDeviceId === d.id ? 'Hide' : 'Certificate'}</button>
+                </td>
+                {isAdmin && (
+                  <td style={{ textAlign: 'right', whiteSpace: 'nowrap' }}>
+                    {d.isActive ? (
+                      <button onClick={() => setDisablingId(d.id)}>Disable</button>
+                    ) : (
+                      <button onClick={() => enable(d.id)}>Enable</button>
+                    )}{' '}
+                    <button onClick={() => remove(d.id)}>Delete</button>
+                  </td>
+                )}
+              </tr>
+              {locationDeviceId === d.id && (
+                <tr>
+                  <td colSpan={columnCount} style={{ padding: '0.75rem', background: '#fafafa' }}>
+                    {locationLoading && <p style={{ color: '#666', margin: 0 }}>Loading last known position…</p>}
+                    {!locationLoading && locationResult && !locationResult.point && (
+                      <p style={{ color: '#888', margin: 0 }}>No location data yet for {d.name}.</p>
+                    )}
+                    {!locationLoading && locationResult?.point && (
+                      <>
+                        <p style={{ color: '#666', margin: '0 0 0.5rem' }}>
+                          Last position {formatRelativeTime(locationResult.point.recordedAt)}
+                          {locationResult.job && <> · job {locationResult.job.ticketNumber} — {locationResult.job.title}</>}
+                        </p>
+                        <JobMap points={[locationResult.point]} heightPx={320} />
+                      </>
+                    )}
+                  </td>
+                </tr>
               )}
-            </tr>
+              {certDeviceId === d.id && (
+                <tr>
+                  <td colSpan={columnCount} style={{ padding: '0.75rem', background: '#fafafa' }}>
+                    {certLoading && <p style={{ color: '#666', margin: 0 }}>Loading certificate…</p>}
+                    {!certLoading && !certInfo && !d.serialNumber && (
+                      <p style={{ color: '#888', margin: 0 }}>Set a serial number on {d.name} before issuing a certificate.</p>
+                    )}
+                    {!certLoading && !certInfo && d.serialNumber && (
+                      <>
+                        <p style={{ color: '#888', margin: '0 0 0.5rem' }}>No certificate issued for {d.name} yet.</p>
+                        <button onClick={() => issueCert(d.id)} disabled={certBusy}>
+                          Issue certificate
+                        </button>
+                      </>
+                    )}
+                    {!certLoading && certInfo && (
+                      <>
+                        <p style={{ margin: '0 0 0.5rem' }}>
+                          CN <code>{certInfo.commonName}</code> · fingerprint <code>{certInfo.fingerprint}</code>
+                          <br />
+                          issued {new Date(certInfo.issuedAt).toLocaleString()} · expires{' '}
+                          {new Date(certInfo.expiresAt).toLocaleString()}
+                        </p>
+                        <div style={{ display: 'flex', gap: '0.5rem' }}>
+                          <button onClick={() => downloadText(`/api/orgs/${orgId}/devices/${d.id}/certificate/cert`, `${certInfo.serialNumber}.crt`)}>
+                            Download cert
+                          </button>
+                          <button onClick={() => downloadText(`/api/orgs/${orgId}/devices/${d.id}/certificate/key`, `${certInfo.serialNumber}.key`)}>
+                            Download key
+                          </button>
+                          <button onClick={() => revokeCert(d.id)} disabled={certBusy}>
+                            Revoke
+                          </button>
+                        </div>
+                      </>
+                    )}
+                  </td>
+                </tr>
+              )}
+            </Fragment>
           ))}
           {isAdmin &&
             disablingId &&
             devices.some((d) => d.id === disablingId) && (
               <tr>
-                <td colSpan={6} style={{ padding: '0.75rem', background: '#fff8f8' }}>
+                <td colSpan={columnCount} style={{ padding: '0.75rem', background: '#fff8f8' }}>
                   <form
                     onSubmit={(e) => {
                       e.preventDefault();

web/pages/settings/mqtt-certs.tsx

@@ -0,0 +1,145 @@
+import { FormEvent, useCallback, useEffect, useState } from 'react';
+import Layout from '../../components/Layout';
+import { api } from '../../lib/api';
+import { useRequireAuth } from '../../lib/auth-context';
+
+interface CaStatus {
+  initialized: boolean;
+  fingerprint?: string;
+  expiresAt?: string;
+}
+
+async function downloadText(path: string, filename: string) {
+  const res = await fetch(path);
+  if (!res.ok) {
+    throw new Error(`Download failed (${res.status})`);
+  }
+  const text = await res.text();
+  const blob = new Blob([text], { type: 'application/x-pem-file' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+export default function MqttCertsPage() {
+  const { user, activeOrg, loading } = useRequireAuth();
+  const isAdmin = activeOrg?.role === 'ORG_ADMIN';
+
+  const [status, setStatus] = useState<CaStatus | null>(null);
+  const [hostname, setHostname] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+
+  const reload = useCallback(() => {
+    if (!isAdmin) {
+      return;
+    }
+    api
+      .get<CaStatus>('/api/certificates/ca')
+      .then((s) => {
+        setStatus(s);
+        setError(null);
+      })
+      .catch((err) => setError(err.message));
+  }, [isAdmin]);
+
+  useEffect(reload, [reload]);
+
+  const initCa = async () => {
+    try {
+      await api.post('/api/certificates/ca/init', {});
+      setNotice('CA initialized. Restart the mosquitto container to enable the 8883 listener if this is the first setup.');
+      reload();
+    } catch (err: any) {
+      setError(err.message);
+    }
+  };
+
+  const provision = async (e: FormEvent) => {
+    e.preventDefault();
+    try {
+      await api.post('/api/certificates/mqtt/provision', { hostname });
+      setNotice('Broker certificate provisioned. Run `docker compose restart mosquitto` to pick it up.');
+      setHostname('');
+    } catch (err: any) {
+      setError(err.message);
+    }
+  };
+
+  if (loading || !user) {
+    return null;
+  }
+
+  if (!isAdmin) {
+    return (
+      <Layout title="MQTT Certificates">
+        <h1>MQTT Certificates</h1>
+        <p>Only organization admins can manage the device certificate authority.</p>
+      </Layout>
+    );
+  }
+
+  return (
+    <Layout title="MQTT Certificates">
+      <h1>MQTT Certificates</h1>
+      <p style={{ color: '#666' }}>
+        Field devices authenticate to the MQTT broker with a client certificate (port 8883). The certificate's serial
+        number becomes its MQTT identity, scoping it to <code>devices/&lt;serial&gt;/#</code>. Issue device
+        certificates from the <a href="/settings/devices">Devices</a> page once the CA below is set up.
+      </p>
+      {error && <p style={{ color: '#c62828' }}>{error}</p>}
+      {notice && <p style={{ color: '#388e3c' }}>{notice}</p>}
+
+      <section style={{ border: '1px solid #ddd', borderRadius: 6, padding: '1rem', marginBottom: '1.5rem' }}>
+        <h2 style={{ marginTop: 0, fontSize: '1.1rem' }}>Certificate authority</h2>
+        {!status && <p style={{ color: '#666' }}>Loading…</p>}
+        {status && !status.initialized && (
+          <>
+            <p style={{ color: '#888' }}>No CA has been initialized yet.</p>
+            <button onClick={initCa}>Initialize CA</button>
+          </>
+        )}
+        {status && status.initialized && (
+          <>
+            <p style={{ margin: '0.25rem 0' }}>
+              <strong>Fingerprint:</strong> <code>{status.fingerprint}</code>
+            </p>
+            <p style={{ margin: '0.25rem 0' }}>
+              <strong>Expires:</strong> {status.expiresAt ? new Date(status.expiresAt).toLocaleString() : '—'}
+            </p>
+            <button onClick={() => downloadText('/api/certificates/ca/download', 'ca.crt')}>Download CA certificate</button>
+          </>
+        )}
+      </section>
+
+      <section style={{ border: '1px solid #ddd', borderRadius: 6, padding: '1rem' }}>
+        <h2 style={{ marginTop: 0, fontSize: '1.1rem' }}>Broker server certificate</h2>
+        <p style={{ color: '#666' }}>
+          Issues (or re-issues) the server certificate the broker presents on port 8883, signed by the CA above.
+        </p>
+        <form onSubmit={provision} style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+          <input
+            placeholder="broker hostname (e.g. mqtt.example.com)"
+            value={hostname}
+            onChange={(e) => setHostname(e.target.value)}
+            required
+            style={{ padding: '0.4rem', width: 260 }}
+          />
+          <button type="submit" disabled={!status?.initialized}>
+            Provision
+          </button>
+        </form>
+      </section>
+
+      <p style={{ color: '#999', fontSize: '0.85rem', marginTop: '1.5rem' }}>
+        Mosquitto doesn't hot-reload its config or certificate files — a manual <code>docker compose restart
+        mosquitto</code> is required after initializing the CA or re-provisioning the broker certificate. Revoking a
+        device certificate deletes its database record only; it isn't broker-enforced (no CRL/OCSP), so a revoked
+        certificate still authenticates until it expires.
+      </p>
+    </Layout>
+  );
+}