browser-vault-gui/SECURITY_CREDENTIALS.md

# Saved Credentials Feature - Security Considerations

## ⚠️ WARNING: USE AT YOUR OWN RISK

This feature allows you to save Vault credentials (tokens, usernames, passwords) in your browser's localStorage for convenience. **This is NOT recommended for production or sensitive environments.**

## How It Works

### Saving Credentials

1. When logging in, check the **"⚠️ Save credentials locally"** checkbox
2. A security warning modal will appear on first use
3. Read and acknowledge the risks
4. Credentials are saved to localStorage (plain text)
5. On next login, credentials are pre-filled

### Visual Indicators

- Servers with saved credentials show a **🔓 Saved Credentials** badge
- The checkbox is pre-checked if credentials exist
- Warning styling (yellow/orange) throughout the UI

### Removing Saved Credentials

**Option 1: Uncheck the box**
- Uncheck "Save credentials locally"
- Login again
- Credentials are removed from localStorage

**Option 2: Remove the server**
- Delete the server from the list
- All associated data (including credentials) is removed

## Security Risks

### ❌ What's Wrong With Saving Credentials

1. **Plain Text Storage**
   - Credentials are stored unencrypted in localStorage
   - Easily accessible via browser DevTools (`localStorage.getItem('vaultServers')`)
   - No encryption, obfuscation, or protection

2. **Browser Extension Access**
   - Any browser extension can read localStorage
   - Malicious extensions can steal credentials
   - No way to restrict access

3. **Shared Computer Risk**
   - Anyone with physical access can:
     - Open browser DevTools
     - Read localStorage
     - Copy credentials

4. **XSS Vulnerability**
   - If the app has an XSS vulnerability, credentials are exposed
   - localStorage is accessible from JavaScript

5. **Browser Sync**
   - Some browsers sync localStorage across devices
   - Credentials might be synced to untrusted devices
   - Shared across all synced browsers

6. **Compliance Issues**
   - Violates most security policies
   - Fails SOC 2, ISO 27001, PCI DSS requirements
   - May violate company IT policies

7. **No Audit Trail**
   - Can't track who accessed credentials
   - No logging of credential usage
   - Can't revoke access if device is lost

8. **Session Persistence**
   - Credentials persist across browser restarts
   - No automatic expiration
   - Manual logout doesn't clear saved credentials

## Viewing Saved Credentials

Anyone can view saved credentials:

```javascript
// Open browser DevTools console
const servers = JSON.parse(localStorage.getItem('vaultServers'))
console.log(servers)

// View credentials for first server
console.log(servers[0].savedCredentials)
```

Output:
```json
{
  "serverId": "my-vault",
  "authMethod": "token",
  "token": "hvs.CAESIJ5U8..."  // ← Exposed!
}
```

## When Is It (Maybe) Acceptable?

Use saved credentials ONLY if ALL of these are true:

### ✅ Acceptable Use Cases

1. **Development/Testing**
   - Non-production Vault server
   - Test data only, no real secrets
   - Personal development machine

2. **Personal Use**
   - Personal computer, not shared
   - You understand the risks
   - You accept responsibility

3. **Low-Value Secrets**
   - Development API keys
   - Non-sensitive test data
   - Throwaway tokens

4. **Short-Lived Tokens**
   - Tokens expire quickly (< 1 hour)
   - Limited permissions
   - Easy to rotate

### ❌ NEVER Use For

1. **Production Vault Servers**
2. **Shared Computers**
3. **Work/Corporate Laptops**
4. **Public Computers**
5. **Sensitive Data**
6. **Long-Lived Tokens**
7. **High-Privilege Accounts**
8. **Compliance-Required Systems**

## Better Alternatives

### Recommended: Don't Save Credentials

1. **Re-login Each Session**
   - Most secure option
   - Only credentials in memory
   - Auto-cleared on logout/close

2. **Use Password Manager**
   - Browser password manager
   - 1Password, LastPass, Bitwarden
   - Encrypted storage
   - Auto-fill support

3. **Short-Lived Tokens**
   - Generate tokens with short TTL
   - Expire after 1-8 hours
   - Automatically revoked

4. **SSO/OIDC Authentication**
   - Use Vault's OIDC auth method
   - Leverage existing SSO
   - No password storage needed

5. **Auto-Logout Timer**
   - Implement session timeout
   - Auto-logout after inactivity
   - Clear credentials from memory

## Implementation Details

### Where Credentials Are Stored

```
localStorage['vaultServers'] = JSON array of server objects

Each server object can contain:
{
  "id": "server-id",
  "name": "My Vault",
  "url": "https://vault.example.com",
  "kvVersion": 2,
  "savedCredentials": {           ← This is the dangerous part
    "serverId": "server-id",
    "authMethod": "token",
    "token": "hvs.CAESIJ5U8..."   ← Plain text!
  }
}
```

### Security Warning Modal

The app shows a prominent warning before saving credentials:

```
⚠️ Security Warning

This is NOT recommended for security reasons!

If you save credentials:
- Your token/password will be stored in plain text
- Anyone with access to your browser can read them
- Browser extensions can access localStorage
- If your computer is compromised, credentials are exposed
- This violates most security policies

Only use this if:
- You're on a personal, secure device
- You understand the security risks
- You're using a development/test Vault server

Better alternatives:
• Use short-lived tokens
• Re-login each session
• Use a password manager
• Enable auto-logout timeout
```

User must explicitly click "I Understand the Risks - Save Anyway"

## Console Warnings

The app logs warnings when credentials are saved:

```
⚠️ Credentials saved to localStorage (insecure!)
```

## Future Improvements

Potential enhancements (not implemented):

1. **Encryption**
   - Encrypt credentials with a master password
   - Use Web Crypto API
   - Still vulnerable but better than plain text

2. **Session Storage**
   - Use sessionStorage instead of localStorage
   - Cleared when tab is closed
   - Doesn't persist across browser restarts

3. **Auto-Expiration**
   - Automatically clear credentials after N days
   - Require re-authentication
   - Reduce exposure window

4. **Browser Warnings**
   - Show persistent warning in UI when credentials are saved
   - Remind user on each login
   - Make it more obvious

5. **Credential Rotation**
   - Prompt user to rotate tokens
   - Integration with Vault's token renewal
   - Automatic token refresh

## Comparison: Save vs Don't Save

| Aspect | Don't Save (Default) | Save Credentials |
|--------|---------------------|------------------|
| **Security** | ✅ Secure | ❌ Insecure |
| **Convenience** | ⚠️ Must re-login | ✅ Auto-login |
| **Compliance** | ✅ Compliant | ❌ Violates policies |
| **Risk if stolen** | ✅ Low | ❌ High |
| **Browser restart** | Must re-login | ✅ Stays logged in |
| **Shared computer** | ✅ Safe | ❌ Dangerous |
| **Audit trail** | ✅ Per-session | ❌ None |
| **Token expiration** | ✅ Natural | ⚠️ Manual |

## Responsible Disclosure

If you find saved credentials in localStorage:

1. **Don't use them** - That would be unauthorized access
2. **Report it** - Inform the credentials owner
3. **Secure the device** - Help secure the compromised device
4. **Rotate credentials** - All saved credentials should be rotated

## Conclusion

### ⚠️ The Bottom Line

**Saving credentials is a convenience feature with serious security trade-offs.**

- ✅ **Convenient** for personal development
- ❌ **Dangerous** for anything sensitive
- ⚠️ **Use at your own risk**

**Default behavior (no saving) is recommended for everyone.**

If you choose to save credentials, you accept full responsibility for any security consequences.

---

*This feature exists because users requested it, but the developers strongly advise against using it in any security-conscious environment.*