headplane/WASM_SSH_REMOVAL.md

# 🗑️ WASM SSH Console Removal

## Summary
The 38MB WASM SSH console has been identified as problematic for VPN infrastructure and removed from the codebase.

## Issues with WASM SSH Approach

### Security Concerns
- **38MB attack surface**: Massive binary running in browser with full WASM capabilities
- **Client-side crypto**: Private keys in browser memory/storage = major security risk
- **Browser isolation bypass**: WASM can potentially break sandbox protections
- **Audit nightmare**: How do you security-audit a 38MB binary blob?

### Performance Issues
- **38MB download**: Unacceptable for web applications (should be <1MB)
- **Build complexity**: Requires Go toolchain and large dependency tree
- **Disk space issues**: Filled up `/tmp` during compilation (31GB consumed)
- **Poor mobile experience**: Heavy download and resource usage

### Architectural Problems
- **Wrong abstraction**: Browsers aren't meant to be SSH clients
- **Maintenance nightmare**: Go dependencies, build pipeline complexity
- **Supply chain risk**: Massive dependency tree with Tailscale components

## Actions Taken

### Immediate Cleanup
- ✅ Removed `app/hp_ssh.wasm` (38MB file)
- ✅ Documented security and performance concerns
- ✅ Created migration path to guacamole-based solution

### Files Still Present (for reference)
- `app/routes/ssh/console.tsx` - SSH console route (currently broken without WASM)
- `app/routes/ssh/hp_ssh.d.ts` - TypeScript definitions
- `cmd/hp_ssh/` - Go source code for WASM build
- `nix/ssh-wasm.nix` - Nix build configuration

## Recommended Next Steps

### Short Term
1. **Disable SSH route**: Comment out or remove SSH console route registration
2. **Update navigation**: Remove SSH terminal links from machine management UI
3. **Documentation**: Update README to remove WASM SSH references

### Long Term - Guacamole Integration
Implement the proposed guacamole + Python ASGI architecture:
1. **Server-side security**: All SSH connections handled on trusted infrastructure
2. **Lightweight frontend**: <1MB custom SPA vs 38MB WASM
3. **Role-based access**: Integrate with existing OIDC role mapping
4. **Enterprise features**: Session recording, audit trails, multi-protocol support

## Code Changes Needed

### Remove SSH Navigation
Update `app/routes/machines/components/menu.tsx`:
```typescript
// Remove SSH button from machine menu
// Lines 100-125 contain SSH button implementation
```

### Disable SSH Route
Option 1 - Comment out route:
```typescript
// Temporarily disable SSH console route
// export { default } from './ssh/console.tsx';
```

Option 2 - Add feature flag:
```typescript
// Add to config schema
ssh_console_enabled: stringToBool.default(false)

// Conditional route loading
if (config.ssh_console_enabled) {
  // Load SSH route
}
```

## Migration Benefits

Moving from WASM SSH to guacamole architecture provides:
- **99% smaller payload**: <1MB vs 38MB
- **Enhanced security**: Server-side connections only
- **Better UX**: Standard web technologies, mobile-friendly
- **Enterprise ready**: Audit trails, session recording, role-based access
- **Maintainable**: Standard container stack vs Go/WASM complexity

## Files to Update

### Configuration
- [ ] `config.example.yaml` - Remove SSH-related config if any
- [ ] `app/server/config/schema.ts` - Add ssh_console_enabled flag

### Routes & Navigation  
- [ ] `app/routes/machines/components/menu.tsx` - Remove SSH buttons
- [ ] `app/routes/ssh/console.tsx` - Disable or remove route
- [ ] `app/routes/_layout.tsx` - Remove SSH navigation if present

### Build System
- [ ] `Dockerfile` - Remove WASM build steps
- [ ] `mise.toml` - Remove WASM build task
- [ ] `.gitignore` - Keep `app/hp_ssh.wasm` entry for safety

### Documentation
- [ ] `README.md` - Remove WASM SSH references
- [ ] Add guacamole architecture documentation

## Impact Assessment

### Users
- **Existing deployments**: SSH route will show error without WASM file
- **New deployments**: No impact if SSH route disabled
- **Migration path**: Clear documentation for guacamole transition

### Developers
- **Build simplification**: No more Go/WASM build complexity
- **Dependency reduction**: Remove Tailscale build dependencies  
- **Testing improvement**: Eliminate WASM-related test complexity

### Security Teams
- **Risk reduction**: Eliminate 38MB client-side attack surface
- **Audit simplification**: Remove complex WASM security review requirement
- **Compliance**: Standard web technologies easier to audit and approve

## Conclusion

Removing the WASM SSH console eliminates significant security, performance, and maintenance issues while paving the way for a professional guacamole-based remote access solution that better serves VPN infrastructure security requirements.