feat(wasm): add browser WASM build target with wasm-bindgen PupClient

Adds wasm32-unknown-unknown as a build target alongside the existing
native and WASI targets. The browser build produces an npm-ready package
with a PupClient JS class exposed via wasm-bindgen.

- Add [lib] section and `browser` feature flag to Cargo.toml
- Create src/lib.rs with PupClient + PupClientOptions wasm-bindgen exports
  (18 typed methods + 5 raw HTTP methods, returns native JS objects)
- Gate env/fs APIs in config.rs behind #[cfg(not(feature = "browser"))],
  add Config::from_params() for browser use
- Add LocalStorageBackend in auth/storage.rs for browser token persistence
- Make auth/crypto deps (rand, sha2, base64, aes-gcm, etc.) optional to
  avoid getrandom v0.3 issues on wasm32-unknown-unknown
- Add getrandom_backend="wasm_js" rustflag in .cargo/config.toml
- Add browser-wasm-build CI job, add pkg/ to .gitignore

Build: wasm-pack build --target web --no-default-features --features browser
Output: 479KB .wasm + JS/TS bindings with full type definitions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: platinummonkey

.cargo/config.toml

@@ -1,2 +1,6 @@
 [target.wasm32-wasip2]
 runner = "wasmtime run --"
+
+# getrandom 0.3 requires explicit backend selection for browser WASM
+[target.wasm32-unknown-unknown]
+rustflags = ['--cfg', 'getrandom_backend="wasm_js"']

.github/workflows/ci.yml

@@ -100,6 +100,22 @@ jobs:
       - name: Report WASM size
         run: ls -lh target/wasm32-wasip2/release/pup.wasm
 
+  browser-wasm-build:
+    name: Browser WASM Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - name: Install wasm-pack
+        run: cargo install wasm-pack
+      - name: Build
+        run: wasm-pack build --target web --no-default-features --features browser
+      - name: Report size
+        run: ls -lh pkg/pup_wasm_bg.wasm
+
   binary-size:
     name: Binary Size
     runs-on: ubuntu-latest

.gitignore

@@ -21,6 +21,9 @@ Thumbs.db
 .env.local
 .envrc
 
+# wasm-pack output
+pkg/
+
 # Test artifacts
 tests/mockdd/mockdd
 tests/compare_bin

Cargo.lock

@@ -3,6 +3,11 @@ name = "pup"
 version = "0.22.0"
 edition = "2021"
 
+[lib]
+name = "pup_wasm"
+path = "src/lib.rs"
+crate-type = ["cdylib", "rlib"]
+
 [features]
 default = ["native"]
 native = [
@@ -13,15 +18,47 @@ native = [
     "dep:reqwest-middleware",
     "dep:async-trait",
     "dep:task-local-extensions",
+    "dep:sha2",
+    "dep:base64",
+    "dep:rand",
+    "dep:url",
+    "dep:aes-gcm",
+    "dep:uuid",
+    "dep:chrono",
+    "dep:regex",
+    "dep:clap",
+    "dep:clap_complete",
     "tokio/full",
     "comfy-table/tty",
 ]
-wasi = ["tokio/rt", "tokio/macros", "reqwest/rustls-tls"]
+wasi = [
+    "dep:sha2",
+    "dep:base64",
+    "dep:rand",
+    "dep:url",
+    "dep:aes-gcm",
+    "dep:uuid",
+    "dep:chrono",
+    "dep:regex",
+    "dep:clap",
+    "dep:clap_complete",
+    "tokio/rt",
+    "tokio/macros",
+    "reqwest/rustls-tls",
+]
+browser = [
+    "dep:wasm-bindgen",
+    "dep:wasm-bindgen-futures",
+    "dep:js-sys",
+    "dep:web-sys",
+    "dep:serde-wasm-bindgen",
+    "dep:getrandom",
+]
 
 [dependencies]
-# CLI
-clap = { version = "4", features = ["derive"] }
-clap_complete = "4.5.66"
+# CLI (optional — not needed for browser WASM library)
+clap = { version = "4", features = ["derive"], optional = true }
+clap_complete = { version = "4.5.66", optional = true }
 
 # Async runtime (features selected by native/wasi feature flags)
 tokio = { version = "1", default-features = false }
@@ -31,30 +68,30 @@ serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1", features = ["preserve_order"] }
 serde_yaml = "0.9"
 
-# HTTP (version-matched to DD client for native; used directly for WASI)
+# HTTP (version-matched to DD client for native; used directly for WASI/browser)
 reqwest = { version = "0.11", features = ["json"] }
 
 # Error handling
 anyhow = "1"
 
 # UUID parsing (version-matched to DD client)
-uuid = "1"
+uuid = { version = "1", optional = true }
 
 # Time
-chrono = "0.4"
-regex = "1"
+chrono = { version = "0.4", optional = true }
+regex = { version = "1", optional = true }
 
 # Output formatting (tty feature disabled for WASM — no crossterm)
 comfy-table = { version = "7", default-features = false }
 
-# Auth — OAuth2 PKCE + token storage
-sha2 = "0.10"
-base64 = "0.22"
-rand = "0.9"
-url = "2"
+# Auth — OAuth2 PKCE + token storage (optional — not needed for browser)
+sha2 = { version = "0.10", optional = true }
+base64 = { version = "0.22", optional = true }
+rand = { version = "0.9", optional = true }
+url = { version = "2", optional = true }
 
-# Crypto for fallback storage
-aes-gcm = "0.10"
+# Crypto for fallback storage (optional — not needed for browser)
+aes-gcm = { version = "0.10", optional = true }
 
 # ---- Native-only dependencies ----
 
@@ -74,3 +111,13 @@ dirs = { version = "6", optional = true }
 
 # Browser opening for OAuth login
 open = { version = "5", optional = true }
+
+# ---- Browser WASM dependencies (wasm-bindgen) ----
+wasm-bindgen = { version = "0.2", optional = true }
+wasm-bindgen-futures = { version = "0.4", optional = true }
+js-sys = { version = "0.3", optional = true }
+web-sys = { version = "0.3", features = ["Window", "Storage"], optional = true }
+serde-wasm-bindgen = { version = "0.6", optional = true }
+
+# RNG support in browser WASM (getrandom 0.2 with JS backend)
+getrandom = { version = "0.2", features = ["js"], optional = true }

Cargo.toml

@@ -24,13 +24,17 @@ pub trait Storage: Send + Sync {
 pub enum BackendType {
     Keychain,
     File,
+    #[cfg(feature = "browser")]
+    LocalStorage,
 }
 
 impl std::fmt::Display for BackendType {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             BackendType::Keychain => write!(f, "keychain"),
             BackendType::File => write!(f, "file"),
+            #[cfg(feature = "browser")]
+            BackendType::LocalStorage => write!(f, "localStorage"),
         }
     }
 }
@@ -268,6 +272,95 @@ impl Storage for InMemoryStorage {
     }
 }
 
+// ---------------------------------------------------------------------------
+// LocalStorage backend (browser WASM) — persists tokens across page reloads
+// ---------------------------------------------------------------------------
+
+#[cfg(feature = "browser")]
+pub struct LocalStorageBackend;
+
+#[cfg(feature = "browser")]
+impl LocalStorageBackend {
+    fn storage() -> Result<web_sys::Storage> {
+        let window = web_sys::window()
+            .ok_or_else(|| anyhow::anyhow!("no global window object"))?;
+        window
+            .local_storage()
+            .map_err(|_| anyhow::anyhow!("localStorage not available"))?
+            .ok_or_else(|| anyhow::anyhow!("localStorage returned None"))
+    }
+
+    fn get_item(key: &str) -> Result<Option<String>> {
+        let storage = Self::storage()?;
+        storage
+            .get_item(key)
+            .map_err(|_| anyhow::anyhow!("failed to read from localStorage"))
+    }
+
+    fn set_item(key: &str, value: &str) -> Result<()> {
+        let storage = Self::storage()?;
+        storage
+            .set_item(key, value)
+            .map_err(|_| anyhow::anyhow!("failed to write to localStorage"))
+    }
+
+    fn remove_item(key: &str) -> Result<()> {
+        let storage = Self::storage()?;
+        storage
+            .remove_item(key)
+            .map_err(|_| anyhow::anyhow!("failed to remove from localStorage"))
+    }
+}
+
+#[cfg(feature = "browser")]
+impl Storage for LocalStorageBackend {
+    fn backend_type(&self) -> BackendType {
+        BackendType::LocalStorage
+    }
+
+    fn storage_location(&self) -> String {
+        "browser localStorage".to_string()
+    }
+
+    fn save_tokens(&self, site: &str, tokens: &TokenSet) -> Result<()> {
+        let key = format!("pup_tokens_{}", sanitize(site));
+        let json = serde_json::to_string(tokens)?;
+        Self::set_item(&key, &json)
+    }
+
+    fn load_tokens(&self, site: &str) -> Result<Option<TokenSet>> {
+        let key = format!("pup_tokens_{}", sanitize(site));
+        match Self::get_item(&key)? {
+            Some(json) => Ok(Some(serde_json::from_str(&json)?)),
+            None => Ok(None),
+        }
+    }
+
+    fn delete_tokens(&self, site: &str) -> Result<()> {
+        let key = format!("pup_tokens_{}", sanitize(site));
+        Self::remove_item(&key)
+    }
+
+    fn save_client_credentials(&self, site: &str, creds: &ClientCredentials) -> Result<()> {
+        let key = format!("pup_client_{}", sanitize(site));
+        let json = serde_json::to_string(creds)?;
+        Self::set_item(&key, &json)
+    }
+
+    fn load_client_credentials(&self, site: &str) -> Result<Option<ClientCredentials>> {
+        let key = format!("pup_client_{}", sanitize(site));
+        match Self::get_item(&key)? {
+            Some(json) => Ok(Some(serde_json::from_str(&json)?)),
+            None => Ok(None),
+        }
+    }
+
+    fn delete_client_credentials(&self, site: &str) -> Result<()> {
+        let key = format!("pup_client_{}", sanitize(site));
+        Self::remove_item(&key)
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Factory — auto-detect backend, with fallback
 // ---------------------------------------------------------------------------
@@ -307,11 +400,16 @@ fn detect_backend() -> Box<dyn Storage> {
     }
 }
 
-#[cfg(target_arch = "wasm32")]
+#[cfg(all(target_arch = "wasm32", not(feature = "browser")))]
 fn detect_backend() -> Box<dyn Storage> {
     Box::new(InMemoryStorage)
 }
 
+#[cfg(feature = "browser")]
+fn detect_backend() -> Box<dyn Storage> {
+    Box::new(LocalStorageBackend)
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------