feat: client-side QR claim — phone verifies receiver, not server

The cloud server can't reach the receiver (different network). Moved
the verification + device discovery to the phone (which IS on LAN):
1. Phone verifies token with receiver directly
2. Phone discovers tanks from receiver's /api/data
3. Phone sends verified data to cloud server
4. Server creates site + MQTT credentials
5. Phone pushes MQTT config to receiver directly

This works because QR scanning is always done locally (user is
standing next to the receiver). After linking, everything is remote
via MQTT over TLS.

Author: Ravi Singh

pwa/client/src/pages/LinkDevice.jsx

@@ -9,11 +9,9 @@ import { api } from '../utils/api.js';
 /**
  * QR Code Claim Page — handles /link?id=...&token=...&ip=...
  *
- * Flow:
- *  1. User scans QR from receiver's web UI → opens this URL
- *  2. If not logged in → redirect to /login with return URL
- *  3. If logged in → auto-claim the device via POST /api/link/claim
- *  4. On success → redirect to dashboard
+ * Architecture: The phone (on LAN) talks directly to the receiver to verify
+ * the token and discover devices. The cloud server only creates DB records
+ * and MQTT credentials — it never needs LAN access to the receiver.
  */
 export default function LinkDevice() {
   const [searchParams] = useSearchParams();
@@ -24,58 +22,107 @@ export default function LinkDevice() {
   const token = searchParams.get('token');
   const receiverIp = searchParams.get('ip');
 
-  const [status, setStatus] = useState('linking'); // linking | success | error | missing_params
+  const [status, setStatus] = useState('linking');
   const [message, setMessage] = useState('');
-  const [siteId, setSiteId] = useState(null);
+  const [step, setStep] = useState('');
 
-  // Validate params
   useEffect(() => {
-    if (!deviceId || !token || !receiverIp) {
-      setStatus('missing_params');
-    }
+    if (!deviceId || !token || !receiverIp) setStatus('missing_params');
   }, [deviceId, token, receiverIp]);
 
-  // Auto-claim once authenticated
   useEffect(() => {
     if (authLoading) return;
     if (!user) {
-      // Redirect to login, preserving the link URL for after login
       const returnUrl = `/link?id=${deviceId}&token=${token}&ip=${receiverIp}`;
       navigate(`/login?redirect=${encodeURIComponent(returnUrl)}`);
       return;
     }
     if (status !== 'linking' || !deviceId || !token || !receiverIp) return;
-
     claimDevice();
   }, [user, authLoading, status]);
 
   const claimDevice = async () => {
     try {
+      // Step 1: Verify token directly with receiver (phone is on LAN)
+      setStep('Verifying receiver...');
+      let receiverData;
+      try {
+        const resp = await fetch(`http://${receiverIp}/api/link`, { signal: AbortSignal.timeout(5000) });
+        receiverData = await resp.json();
+      } catch {
+        throw new Error('Could not reach receiver. Make sure your phone is on the same WiFi network as the receiver.');
+      }
+
+      if (receiverData.device_id !== deviceId || receiverData.token !== token) {
+        throw new Error('Invalid or expired link token. Try scanning the QR code again.');
+      }
+
+      // Step 2: Discover tanks from receiver
+      setStep('Discovering tanks...');
+      let tanks = [];
+      try {
+        const dataResp = await fetch(`http://${receiverIp}/api/data`, { signal: AbortSignal.timeout(5000) });
+        const data = await dataResp.json();
+        tanks = data.tanks || [];
+      } catch {}
+
+      // Step 3: Get transmitter details
+      let transmitters = [];
+      try {
+        const txResp = await fetch(`http://${receiverIp}/api/transmitters`, { signal: AbortSignal.timeout(5000) });
+        const txData = await txResp.json();
+        transmitters = txData.transmitters || [];
+      } catch {}
+
+      // Step 4: Send everything to cloud server (server creates site + MQTT creds)
+      setStep('Setting up cloud connection...');
       const result = await api.post('/api/link/claim', {
         device_id: deviceId,
-        token,
-        receiver_ip: receiverIp
+        receiver_ip: receiverIp,
+        verified: true,
+        tanks,
+        transmitters,
       });
 
-      setSiteId(result.site_id);
+      // Step 5: Push MQTT config to receiver (phone is on LAN)
+      if (result.mqtt) {
+        setStep('Configuring MQTT on receiver...');
+        try {
+          await fetch(`http://${receiverIp}/api/mqtt`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              host: result.mqtt.mqtt_host,
+              port: result.mqtt.mqtt_port,
+              user: result.mqtt.mqtt_username,
+              pass: result.mqtt.mqtt_password,
+              enabled: true,
+              ha_discovery: false,
+              use_tls: true,
+            }),
+            signal: AbortSignal.timeout(5000),
+          });
+        } catch {
+          // Non-fatal — user can configure MQTT manually
+        }
+      }
 
+      setStatus('success');
+      const mqttMsg = result.mqtt ? ' MQTT auto-configured.' : '';
       if (result.already_linked) {
-        setStatus('success');
-        setMessage('This device is already linked to your account.');
+        setMessage('This device is already linked to your account.' + mqttMsg);
       } else {
-        setStatus('success');
-        setMessage(`Linked successfully! ${result.device_count || 0} tank${result.device_count !== 1 ? 's' : ''} discovered.`);
+        setMessage(`Linked successfully! ${result.device_count || 0} tank${result.device_count !== 1 ? 's' : ''} discovered.${mqttMsg}`);
       }
     } catch (err) {
       setStatus('error');
       setMessage(err.message || 'Failed to link device');
     }
   };
 
-  // Missing params
   if (status === 'missing_params') {
     return (
-      <div className="min-h-screen bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
+      <div className="min-h-[100dvh] bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
         <ErrorIcon />
         <h2 className="text-xl font-bold text-white mt-4 mb-2">Invalid Link</h2>
         <p className="text-slate-400 text-sm mb-6">This link is missing required parameters. Please scan the QR code from your receiver's web UI again.</p>
@@ -87,22 +134,20 @@ export default function LinkDevice() {
     );
   }
 
-  // Linking in progress
   if (status === 'linking') {
     return (
-      <div className="min-h-screen bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
+      <div className="min-h-[100dvh] bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
         <div className="w-16 h-16 border-4 border-water/30 border-t-water rounded-full animate-spin mb-6" />
         <h2 className="text-xl font-bold text-white mb-2">Linking Device</h2>
-        <p className="text-slate-400 text-sm">Verifying and connecting your TankSync receiver...</p>
+        <p className="text-slate-400 text-sm">{step || 'Connecting...'}</p>
         <p className="text-slate-500 text-xs mt-2 font-mono">{deviceId}</p>
       </div>
     );
   }
 
-  // Success
   if (status === 'success') {
     return (
-      <div className="min-h-screen bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
+      <div className="min-h-[100dvh] bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
         <div className="w-20 h-20 rounded-full bg-success/10 flex items-center justify-center mb-6">
           <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="#22C55E" strokeWidth="2.5" strokeLinecap="round">
             <path d="M20 6L9 17l-5-5" />
@@ -119,14 +164,13 @@ export default function LinkDevice() {
     );
   }
 
-  // Error
   return (
-    <div className="min-h-screen bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
+    <div className="min-h-[100dvh] bg-slate-950 flex flex-col items-center justify-center px-6 text-center">
       <ErrorIcon />
       <h2 className="text-xl font-bold text-white mt-4 mb-2">Linking Failed</h2>
       <p className="text-danger text-sm mb-6">{message}</p>
       <div className="flex gap-3 w-full max-w-xs">
-        <button onClick={() => { setStatus('linking'); claimDevice(); }}
+        <button onClick={() => { setStatus('linking'); setStep(''); claimDevice(); }}
           className="flex-1 py-3 rounded-xl bg-water text-white font-semibold active:scale-[0.98] transition-all">
           Try Again
         </button>

pwa/server-cloud/index.js

@@ -279,75 +279,61 @@ app.delete('/api/devices/:id', { preHandler: [app.authenticate] }, async (req, r
 });
 
 // ─── QR CODE DEVICE LINKING ────────────────────────────────────────────────────
+// The phone (on LAN) verifies the receiver token and discovers devices,
+// then sends the pre-verified data here. The server never contacts the receiver.
 
 app.post('/api/link/claim', { preHandler: [app.authenticate] }, async (req, reply) => {
-  const { device_id, token, receiver_ip } = req.body || {};
-  if (!device_id || !token || !receiver_ip) return reply.code(400).send({ error: 'Missing device_id, token, or receiver_ip' });
-
-  let receiverData;
-  try {
-    const resp = await fetch(`http://${receiver_ip}/api/link`, { signal: AbortSignal.timeout(5000) });
-    receiverData = await resp.json();
-  } catch {
-    return reply.code(502).send({ error: 'Could not reach receiver. Make sure the server and receiver are on the same network.' });
-  }
-
-  if (receiverData.device_id !== device_id || receiverData.token !== token)
-    return reply.code(403).send({ error: 'Invalid or expired link token.' });
+  const { device_id, receiver_ip, verified, tanks, transmitters } = req.body || {};
+  if (!device_id || !receiver_ip) return reply.code(400).send({ error: 'Missing device_id or receiver_ip' });
+  if (!verified) return reply.code(400).send({ error: 'Token not verified by client' });
 
+  // Check if already linked
   const existing = await db.get('SELECT id FROM sites WHERE user_id = $1 AND mqtt_device_id = $2', req.user.id, device_id);
-  if (existing) return { site_id: existing.id, message: 'Device already linked', already_linked: true };
+  if (existing) {
+    // Still generate MQTT creds if missing
+    let mqttCreds = null;
+    try { mqttCreds = await generateMqttCredentials(req.user.id, existing.id, device_id); } catch {}
+    return { site_id: existing.id, message: 'Device already linked', already_linked: true, mqtt: mqttCreds };
+  }
 
+  // Create site
   const site = await db.run('INSERT INTO sites (user_id, name, receiver_ip, mqtt_device_id) VALUES ($1, $2, $3, $4)',
     req.user.id, 'My Tank', receiver_ip, device_id);
   const siteId = site.lastInsertRowid;
 
+  // Add discovered tanks (sent by the phone)
   let deviceCount = 0;
-  try {
-    const dataResp = await fetch(`http://${receiver_ip}/api/data`, { signal: AbortSignal.timeout(5000) });
-    const data = await dataResp.json();
-    if (data.tanks?.length > 0) {
-      for (const tank of data.tanks) {
-        try {
-          await db.run('INSERT INTO devices (site_id, lora_address, name) VALUES ($1, $2, $3)', siteId, tank.address, tank.name || `Tank ${tank.address}`);
-          deviceCount++;
-        } catch {}
-      }
+  if (tanks?.length > 0) {
+    for (const tank of tanks) {
+      try {
+        await db.run('INSERT INTO devices (site_id, lora_address, name) VALUES ($1, $2, $3)',
+          siteId, tank.address, tank.name || `Tank ${tank.address}`);
+        deviceCount++;
+      } catch {}
     }
-  } catch {}
+  }
 
-  try {
-    const txResp = await fetch(`http://${receiver_ip}/api/transmitters`, { signal: AbortSignal.timeout(5000) });
-    const txData = await txResp.json();
-    if (txData.transmitters) {
-      for (const tx of txData.transmitters) {
-        await db.run('UPDATE devices SET tank_capacity_l=$1, min_distance_cm=$2, max_distance_cm=$3, fw_version=$4 WHERE site_id=$5 AND lora_address=$6',
-          tx.capacity, tx.min_dist, tx.max_dist, tx.fw_version || null, siteId, tx.address);
-      }
+  // Update with transmitter details
+  if (transmitters?.length > 0) {
+    for (const tx of transmitters) {
+      await db.run('UPDATE devices SET tank_capacity_l=$1, min_distance_cm=$2, max_distance_cm=$3, fw_version=$4 WHERE site_id=$5 AND lora_address=$6',
+        tx.capacity, tx.min_dist, tx.max_dist, tx.fw_version || null, siteId, tx.address);
     }
-  } catch {}
+  }
 
-  // 6. Generate MQTT credentials and push to receiver
-  let mqtt_configured = false;
+  // Generate MQTT credentials (server-side only — phone pushes to receiver)
   let mqttCreds = null;
   try {
     mqttCreds = await generateMqttCredentials(req.user.id, siteId, device_id);
-    mqtt_configured = await pushMqttToReceiver(receiver_ip, mqttCreds);
-    if (mqtt_configured) {
-      app.log.info(`MQTT auto-configured on receiver ${receiver_ip} — user ${mqttCreds.mqtt_username}`);
-    }
   } catch (err) {
     app.log.warn(`MQTT credential setup failed: ${err.message}`);
   }
 
   return {
     site_id: siteId,
     device_count: deviceCount,
-    mqtt_configured,
-    mqtt_host: mqttCreds?.mqtt_host,
-    message: mqtt_configured
-      ? 'Device linked and MQTT configured automatically'
-      : 'Device linked. Configure MQTT manually in the receiver web UI.',
+    mqtt: mqttCreds,
+    message: 'Device linked successfully',
   };
 });