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>
+  );
+}

web/pages/sim/index.tsx

@@ -18,9 +18,11 @@ interface SentEntry {
   lat: number;
   lng: number;
   depth: number;
+  transport: Transport;
 }
 
 type MessageType = 'log' | 'status';
+type Transport = 'relay' | 'mqtts';
 
 const UTILITIES = ['GAS', 'WATER', 'ELECTRIC', 'SEWER', 'TELECOM', 'CATV', 'FIBER', 'STEAM', 'UNKNOWN'];
 const FIX_TYPES = ['FIXED_RTK', 'FLOAT_RTK', 'DGPS', 'AUTONOMOUS', 'NONE'];
@@ -51,6 +53,7 @@ export default function SimulatorPage() {
   const [newTitle, setNewTitle] = useState('');
 
   const [messageType, setMessageType] = useState<MessageType>('log');
+  const [transport, setTransport] = useState<Transport>('relay');
   const [serial, setSerial] = useState('');
   const [utility, setUtility] = useState('GAS');
   const [fixType, setFixType] = useState('FIXED_RTK');
@@ -137,6 +140,7 @@ export default function SimulatorPage() {
       await api.post(`/api/orgs/${orgId}/sim/publish`, {
         type: messageType,
         serial,
+        transport,
         jobId,
         lat: pos.lat,
         lng: pos.lng,
@@ -160,7 +164,15 @@ export default function SimulatorPage() {
       setCount(seq);
       setSent((prev) =>
         [
-          { at: new Date().toLocaleTimeString(), seq, type: messageType, lat: pos.lat, lng: pos.lng, depth: pointDepth },
+          {
+            at: new Date().toLocaleTimeString(),
+            seq,
+            type: messageType,
+            lat: pos.lat,
+            lng: pos.lng,
+            depth: pointDepth,
+            transport,
+          },
           ...prev,
         ].slice(0, 25),
       );
@@ -216,7 +228,7 @@ export default function SimulatorPage() {
       <main style={{ maxWidth: 720, margin: '0 auto', padding: '1.5rem' }}>
         <p style={{ color: '#666' }}>
           Simulates a locator receiver publishing GPS + telemetry to the MQTT broker at{' '}
-          <code>devices/{serial || '<serial>'}/log</code>, exactly as a real device would.
+          <code>devices/{serial || '<serial>'}/log</code>.
         </p>
         {error && <p style={{ color: '#c62828' }}>{error}</p>}
 
@@ -232,6 +244,24 @@ export default function SimulatorPage() {
           </label>
         </fieldset>
 
+        <fieldset style={{ marginBottom: '1rem', border: '1px solid #ddd', borderRadius: 8, padding: '1rem' }}>
+          <legend>Connection</legend>
+          <label style={{ marginRight: '1.5rem' }}>
+            <input type="radio" checked={transport === 'relay'} onChange={() => setTransport('relay')} /> HTTP relay{' '}
+            <span style={{ color: '#888' }}>— backend forwards it on the broker connection it already holds</span>
+          </label>
+          <label>
+            <input type="radio" checked={transport === 'mqtts'} onChange={() => setTransport('mqtts')} /> MQTTS (device
+            certificate) <span style={{ color: '#888' }}>— connects to port 8883 and authenticates as this serial's own client cert</span>
+          </label>
+          {transport === 'mqtts' && (
+            <p style={{ color: '#999', fontSize: '0.85rem', margin: '0.5rem 0 0' }}>
+              Requires a device with this exact serial number to already exist in this org and have a certificate
+              issued from <a href="/settings/devices">Devices</a>.
+            </p>
+          )}
+        </fieldset>
+
         <fieldset style={{ marginBottom: '1rem', border: '1px solid #ddd', borderRadius: 8, padding: '1rem' }}>
           <legend>Job</legend>
           {!creatingJob ? (
@@ -424,6 +454,7 @@ export default function SimulatorPage() {
               <th>Lat</th>
               <th>Lng</th>
               <th>Depth</th>
+              <th>Via</th>
             </tr>
           </thead>
           <tbody>
@@ -435,11 +466,12 @@ export default function SimulatorPage() {
                 <td>{s.lat.toFixed(7)}</td>
                 <td>{s.lng.toFixed(7)}</td>
                 <td>{s.depth} m</td>
+                <td style={{ color: s.transport === 'mqtts' ? '#2e7d32' : '#888' }}>{s.transport}</td>
               </tr>
             ))}
             {sent.length === 0 && (
               <tr>
-                <td colSpan={6} style={{ padding: '1.5rem', textAlign: 'center', color: '#888' }}>
+                <td colSpan={7} style={{ padding: '1.5rem', textAlign: 'center', color: '#888' }}>
                   No points sent yet.
                 </td>
               </tr>