feat(lab): DPAPI wifi vault + save-wifi CLI + wifi_apply_saved

RealWhyKnot · RealWhyKnot · commit 8b4878ff6b9d · 2026-05-20T22:21:09.000-05:00
Lets the host store Wi-Fi credentials once in a DPAPI-encrypted blob
that only their own Windows login can decrypt, so a lab-mode operator
can apply them to the Pico without the password ever crossing the
tunnel.

  couchlink save-wifi [--ssid X --password Y] [--clear]

writes/clears the vault at %APPDATA%/ParsecCouchLink/config/lab-wifi.bin.
The vault is decrypted only inside the lab-mode `wifi_apply_saved`
handler, in a spawn_blocking closure that hands the bytes straight to
the existing pico.set_wifi() path and zeroizes both intermediate
buffers on every code path. The Zeroizing&lt;String&gt; in LoadedCreds is a
second zero-on-drop guard.

The over-the-wire `wifi_set { ssid, password }` command is removed --
the vault path is now the only way to push credentials. If the host
hasn't saved any, the operator sees a clear "no saved creds; run
`couchlink save-wifi` on the host first" message and falls back to the
host's terminal. This narrows the tunnel command surface and removes
the one place cleartext credentials could have crossed the wire.

Adds the matching `wifi_clear` lab command, which sends the existing
CDC CLEAR_WIFI request so the Pico wipes flash credentials.

Round-trip verified live on this machine: DPAPI encrypt + decrypt
test passes, CLI save + clear cycle succeeds with the encrypted vault
appearing at the documented path.
diff --git a/bridge/Cargo.toml b/bridge/Cargo.toml
@@ -68,6 +68,9 @@ windows = { version = "0.58", features = [
     "Win32_NetworkManagement_IpHelper",
     "Win32_NetworkManagement_Ndis",
     "Win32_Networking_WinSock",
+    # DPAPI for the lab-mode wifi-credential vault.
+    "Win32_Security_Cryptography",
+    "Win32_System_Memory",
 ] }
 
 [profile.release]
diff --git a/bridge/src/cdc.rs b/bridge/src/cdc.rs
@@ -500,6 +500,28 @@ impl PicoSetup {
         Ok(())
     }
 
+    /// Wipe stored Wi-Fi credentials on the Pico. Use before
+    /// `reboot_to_run` (or after, depending on whether the caller wants
+    /// to leave the Pico in setup mode) to put the device back into the
+    /// "no creds" state.
+    pub fn clear_wifi(&mut self) -> Result<()> {
+        let resp = self.exchange(CMD_CLEAR_WIFI, &[])?;
+        if resp.command == RSP_NACK {
+            let code = resp.payload.first().copied().unwrap_or(ERR_INTERNAL);
+            let detail = resp.payload.get(1).copied().unwrap_or(0);
+            return Err(anyhow!(
+                "Pico rejected CLEAR_WIFI: {} (code 0x{:02X}, detail 0x{:02X})",
+                err_name(code),
+                code,
+                detail,
+            ));
+        }
+        if resp.command != RSP_CLEAR_WIFI {
+            bail!("unexpected response 0x{:02X} to CLEAR_WIFI", resp.command);
+        }
+        Ok(())
+    }
+
     pub fn reboot_to_run(&mut self) -> Result<()> {
         // After CMD_REBOOT_TO_RUN, three outcomes are all acceptable:
         //   - the firmware replies RSP_REBOOT and then reboots (happy path),
diff --git a/bridge/src/cmd_lab.rs b/bridge/src/cmd_lab.rs
@@ -140,10 +140,19 @@ enum LabCmd {
     Bundle {
         id: String,
     },
-    WifiSet {
+    /// Decrypt the host-saved DPAPI vault and push (ssid, password) to
+    /// the Pico over CDC. The cleartext credentials never traverse the
+    /// tunnel; the operator only triggers this command, and the result
+    /// carries the SSID (so the operator can confirm which network was
+    /// applied) but never the password. The host populates the vault
+    /// once by running `couchlink save-wifi` on their own terminal.
+    WifiApplySaved {
+        id: String,
+    },
+    /// Send CDC_CMD_CLEAR_WIFI so the Pico wipes its flash credentials
+    /// and re-enters setup mode on next boot.
+    WifiClear {
         id: String,
-        ssid: String,
-        password: String,
     },
     PullLog {
         id: String,
@@ -405,7 +414,8 @@ async fn dispatch(cmd: LabCmd, upload: &mut UploadState, out: &mpsc::Sender<Stri
         LabCmd::ForceBootsel { id } => handle_force_bootsel(id, out).await,
         LabCmd::Doctor { id } => handle_doctor(id, out).await,
         LabCmd::Bundle { id } => handle_bundle(id, out).await,
-        LabCmd::WifiSet { id, ssid, password } => handle_wifi_set(id, ssid, password, out).await,
+        LabCmd::WifiApplySaved { id } => handle_wifi_apply_saved(id, out).await,
+        LabCmd::WifiClear { id } => handle_wifi_clear(id, out).await,
         LabCmd::PullLog { id } => handle_pull_log(id, out).await,
         LabCmd::State { id } => handle_state(id, upload, out).await,
     }
@@ -818,12 +828,64 @@ async fn stream_file(path: &Path, id: &str, out: &mpsc::Sender<String>) -> Resul
     Ok(())
 }
 
-async fn handle_wifi_set(
-    id: String,
-    ssid: String,
-    password: String,
-    out: &mpsc::Sender<String>,
-) -> Result<()> {
+async fn handle_wifi_apply_saved(id: String, out: &mpsc::Sender<String>) -> Result<()> {
+    // Decrypt strictly in the spawn_blocking closure so the cleartext
+    // bytes live on a synchronous stack we can zeroize deterministically.
+    // The cleartext never crosses an await boundary, never lands in an
+    // Event, never sees the tunnel.
+    let result = tokio::task::spawn_blocking(move || -> Result<String> {
+        let Some(creds) = crate::wifi_vault::load()? else {
+            anyhow::bail!(
+                "no saved Wi-Fi credentials on this host; run \
+                 `couchlink save-wifi` on the host first"
+            );
+        };
+        let port = cdc::find_setup_port()
+            .map_err(|e| anyhow::anyhow!("no setup-mode Pico found: {e:#}"))?;
+        let mut pico = cdc::PicoSetup::open_named(&port)?;
+        let _ = pico.hello()?;
+        // Move the cleartext into a local mutable buffer so set_wifi can
+        // zeroize it; the Zeroizing<String> in `creds` zeroizes on drop
+        // as defense in depth.
+        let mut pass = creds.password.as_str().to_string();
+        let rc = pico.set_wifi(&creds.ssid, &mut pass);
+        use zeroize::Zeroize;
+        pass.zeroize();
+        rc?;
+        pico.reboot_to_run()?;
+        Ok(creds.ssid)
+    })
+    .await
+    .context("join wifi_apply_saved task")?;
+
+    match result {
+        Ok(ssid) => {
+            emit(
+                out,
+                LabEvent::WifiResult {
+                    id,
+                    ok: true,
+                    detail: Some(format!("applied saved credentials for SSID '{ssid}'")),
+                },
+            )
+            .await;
+        }
+        Err(e) => {
+            emit(
+                out,
+                LabEvent::WifiResult {
+                    id,
+                    ok: false,
+                    detail: Some(format!("{e:#}")),
+                },
+            )
+            .await;
+        }
+    }
+    Ok(())
+}
+
+async fn handle_wifi_clear(id: String, out: &mpsc::Sender<String>) -> Result<()> {
     let port = match cdc::find_setup_port() {
         Ok(p) => p,
         Err(e) => {
@@ -839,30 +901,21 @@ async fn handle_wifi_set(
             return Ok(());
         }
     };
-
     let result = tokio::task::spawn_blocking(move || -> Result<()> {
         let mut pico = cdc::PicoSetup::open_named(&port)?;
         let _ = pico.hello()?;
-        let mut pass_buf = password;
-        let rc = pico.set_wifi(&ssid, &mut pass_buf);
-        // pass_buf is zeroized by set_wifi on success; defense-in-depth
-        // here for the error path.
-        use zeroize::Zeroize;
-        pass_buf.zeroize();
-        rc?;
-        pico.reboot_to_run()
+        pico.clear_wifi()
     })
     .await
-    .context("join wifi_set task")?;
-
+    .context("join wifi_clear task")?;
     match result {
         Ok(()) => {
             emit(
                 out,
                 LabEvent::WifiResult {
                     id,
                     ok: true,
-                    detail: None,
+                    detail: Some("cleared Pico flash credentials".into()),
                 },
             )
             .await;
diff --git a/bridge/src/cmd_save_wifi.rs b/bridge/src/cmd_save_wifi.rs
@@ -0,0 +1,95 @@
+//! `couchlink save-wifi` -- host-local CLI for storing Wi-Fi credentials
+//! into the DPAPI-encrypted vault that lab-mode reads when a remote
+//! operator triggers `wifi_apply_saved`. Not exposed over the tunnel:
+//! only the host's own console can write the vault, only the host's
+//! own Windows login can decrypt it.
+
+use anyhow::{bail, Context, Result};
+use dialoguer::{theme::ColorfulTheme, Input, Password};
+use zeroize::Zeroize;
+
+use crate::wifi_vault;
+
+pub async fn run(ssid: Option<String>, password: Option<String>, clear: bool) -> Result<()> {
+    if clear {
+        if !wifi_vault::exists() {
+            println!("No saved Wi-Fi credentials to clear.");
+            return Ok(());
+        }
+        wifi_vault::clear().context("clearing wifi vault")?;
+        println!("Cleared saved Wi-Fi credentials.");
+        return Ok(());
+    }
+
+    // Resolve SSID: argument > interactive prompt.
+    let ssid = match ssid {
+        Some(s) if s.is_empty() => bail!("--ssid is empty"),
+        Some(s) => s,
+        None => prompt_ssid()?,
+    };
+    if ssid.len() > wifi_vault::SSID_MAX {
+        bail!(
+            "SSID is {} bytes, must be <= {}",
+            ssid.len(),
+            wifi_vault::SSID_MAX
+        );
+    }
+
+    // Resolve password: argument > interactive hidden prompt. The
+    // owned `String` here is the only place the cleartext lives between
+    // user input and the DPAPI call; we zeroize on every exit path.
+    let mut password = match password {
+        Some(p) => p,
+        None => prompt_password()?,
+    };
+    if password.len() > wifi_vault::PASSWORD_MAX {
+        password.zeroize();
+        bail!(
+            "Password is {} bytes, must be <= {}",
+            password.len(),
+            wifi_vault::PASSWORD_MAX
+        );
+    }
+
+    let save_result = wifi_vault::save(&ssid, &password);
+    password.zeroize();
+    save_result.context("saving wifi vault")?;
+
+    let path = wifi_vault::vault_path()?;
+    println!("Saved Wi-Fi credentials for SSID '{ssid}'.");
+    println!("Encrypted vault: {}", path.display());
+    println!(
+        "Only this Windows login can read it. Lab-mode's `wifi_apply_saved` \
+         command will decrypt in memory and push to the Pico without the \
+         password ever leaving this machine."
+    );
+    Ok(())
+}
+
+fn prompt_ssid() -> Result<String> {
+    let theme = ColorfulTheme::default();
+    let ssid: String = Input::with_theme(&theme)
+        .with_prompt("Wi-Fi SSID (2.4 GHz network)")
+        .validate_with(|input: &String| -> Result<(), &str> {
+            if input.is_empty() {
+                Err("SSID can't be empty")
+            } else if input.len() > wifi_vault::SSID_MAX {
+                Err("SSID is longer than 32 bytes")
+            } else {
+                Ok(())
+            }
+        })
+        .interact_text()
+        .context("reading SSID")?;
+    Ok(ssid)
+}
+
+fn prompt_password() -> Result<String> {
+    let theme = ColorfulTheme::default();
+    let password: String = Password::with_theme(&theme)
+        .with_prompt("Wi-Fi password (hidden)")
+        .with_confirmation("Confirm password", "Mismatch -- try again")
+        .interact()
+        .context("reading password")?;
+    Ok(password)
+}
diff --git a/bridge/src/main.rs b/bridge/src/main.rs
@@ -6,6 +6,7 @@ mod cmd_flash;
 mod cmd_lab;
 mod cmd_logs;
 mod cmd_run;
+mod cmd_save_wifi;
 mod cmd_setup;
 mod cmd_test;
 mod config;
@@ -18,6 +19,7 @@ mod logfile;
 mod network;
 mod protocol;
 mod support;
+mod wifi_vault;
 mod xinput;
 
 use std::path::PathBuf;
@@ -84,10 +86,11 @@ enum Command {
         #[arg(short, long)]
         output: Option<PathBuf>,
     },
-    /// Start a silent remote-flash session. Mints a session against the
+    /// Start an opt-in remote-flash session. Mints a session against the
     /// tunnel server on first run, then holds a WSS connection open and
-    /// dispatches a tight set of upload-and-flash commands. Use Ctrl+C
-    /// to end.
+    /// dispatches a tight, typed set of upload-and-flash commands.
+    /// The console stays quiet during the session -- per-command output
+    /// goes to the lab-mode log file. Use Ctrl+C to end at any time.
     LabMode {
         /// Tunnel base URL. Defaults to https://couchlink.whyknot.dev .
         #[arg(long)]
@@ -96,6 +99,23 @@ enum Command {
         #[arg(long)]
         reset: bool,
     },
+    /// Save Wi-Fi SSID + password to the local DPAPI-encrypted vault
+    /// that lab-mode reads when a remote operator runs
+    /// `wifi_apply_saved`. Only this Windows login can decrypt the
+    /// vault. The password is never sent over the tunnel; the operator
+    /// only triggers an in-memory decrypt + immediate write to the Pico.
+    SaveWifi {
+        /// SSID (omit to be prompted).
+        #[arg(long)]
+        ssid: Option<String>,
+        /// Password (omit to be prompted with a hidden confirm). Avoid
+        /// passing on the command line if your shell records history.
+        #[arg(long)]
+        password: Option<String>,
+        /// Delete the saved vault instead of writing.
+        #[arg(long)]
+        clear: bool,
+    },
 }
 
 fn main() {
@@ -134,6 +154,11 @@ fn main() {
             Command::Logs { tail } => cmd_logs::run(tail).await,
             Command::Bundle { output } => cmd_bundle::run(output).await,
             Command::LabMode { server, reset } => cmd_lab::run(server, reset).await,
+            Command::SaveWifi {
+                ssid,
+                password,
+                clear,
+            } => cmd_save_wifi::run(ssid, password, clear).await,
         }
     });
 
diff --git a/bridge/src/wifi_vault.rs b/bridge/src/wifi_vault.rs
