browser-vault-gui/USAGE.md

# Usage Guide

## Quick Start

### 1. Install and Run

```bash
npm install
npm run dev
```

Open http://localhost:5173 in your browser.

### 2. Add Your First Vault Server

1. Click **"+ Add Server"**
2. Fill in the form:
   - **Server Name**: e.g., "Production Vault"
   - **Server URL**: e.g., "https://vault.example.com"
   - **Description**: Optional, e.g., "Production environment vault"
3. Click **"Add Server"**

### 3. Connect to Vault

1. Select your server from the list
2. Choose authentication method:
   - **Token**: Paste your vault token
   - **Username & Password**: Enter credentials
   - **LDAP**: Enter LDAP credentials
3. Click **"Connect"**

### 4. Browse Secrets

#### Read a Secret Directly

1. Enter the full path in the "Secret Path" field
   - Example: `secret/data/myapp/database`
2. Press Enter or click **"Read Secret"**
3. The secret data will appear below

#### Search for Secrets

1. Click **"🔍 Search"** button
2. Enter a **Base Path** (where to start searching)
   - Example: `secret/`
3. Enter a **Search Term**
   - Example: `database` (will find all paths containing "database")
4. Click **"Search"**
5. Results appear showing:
   - 📁 Directories (not clickable)
   - 📄 Secrets (clickable to view)
6. Click **"View"** on any secret to read it

### 5. Configure Settings

Click **"⚙️ Settings"** to adjust:

#### Cache Settings
- **Enable cache**: Toggle caching on/off
- **Maximum cache size**: How much data to cache (in MB)
- **Cache expiration**: How long cached data remains valid (in minutes)

#### Search Settings
- **Maximum search depth**: How deep to recurse (prevents infinite loops)
- **Maximum search results**: Limit number of results returned

#### Cache Statistics
View real-time cache usage:
- Total size of cached data
- Number of cached entries
- Age of oldest/newest entries
- **Clear Cache** button to reset

## Advanced Usage

### Understanding the Cache

The cache system prevents excessive API calls to your Vault server:

1. **First Request**: API call is made, result is cached
2. **Subsequent Requests**: Data returned from cache (instant)
3. **Cache Expiration**: After configured time, next request will hit the API again

**Cache Key Format**: `{serverId}:{operation}:{path}`

Example: `abc-123:list:secret/data/myapp/`

### Search Behavior

The recursive search:
1. Lists all items at the base path
2. For each item:
   - If it matches the search term, it's added to results
   - If it's a directory, recursively search inside it
3. Stops when:
   - Max depth is reached
   - Max results are found
   - No more paths to explore

**Performance Tips**:
- Use specific base paths to limit search scope
- Results are cached, so repeated searches are fast
- Adjust max depth for deep directory structures

### Working with Different Auth Methods

#### Token Authentication
```
Token: s.1234567890abcdef
```
Best for: Development, CI/CD, service accounts

#### Username/Password
```
Username: john.doe
Password: ••••••••
```
Best for: Interactive users, testing

#### LDAP
```
Username: john.doe
Password: ••••••••
```
Best for: Enterprise users with LDAP integration

## Examples

### Example 1: Finding Database Credentials

1. Connect to your vault server
2. Click "🔍 Search"
3. Base Path: `secret/`
4. Search Term: `database`
5. View results and click on the relevant secret
6. Copy the credentials you need

### Example 2: Browsing Application Secrets

1. Connect to vault
2. Enter path: `secret/data/myapp/`
3. Note the structure
4. Navigate to specific secrets:
   - `secret/data/myapp/config`
   - `secret/data/myapp/database`
   - `secret/data/myapp/api-keys`

### Example 3: Managing Cache

1. Use the application normally
2. Open Settings to view cache stats
3. If cache grows too large or contains stale data:
   - Adjust cache size limit
   - Reduce expiration time
   - Or click "Clear Cache"

## Troubleshooting

### CORS Errors

If you see CORS errors in the console:

1. Configure your Vault server to allow CORS
2. Add your frontend URL to `cors_allowed_origins`
3. Restart your Vault server

Example Vault config:
```hcl
listener "tcp" {
  cors_enabled = true
  cors_allowed_origins = ["http://localhost:5173"]
}
```

### Authentication Fails

- Verify your token/credentials are correct
- Check token hasn't expired
- Ensure you have proper permissions in Vault
- Check Vault server URL is correct

### Search Returns No Results

- Verify the base path exists and you have permission to list it
- Try a broader search term
- Check max depth isn't too low
- Ensure secrets exist at that path

### Cache Issues

- Clear cache from Settings if data seems stale
- Check cache expiration time isn't too long
- Verify localStorage isn't full (browser limit ~5-10MB)

## Best Practices

1. **Security**:
   - Always use HTTPS in production
   - Don't share tokens
   - Log out when done
   - Clear cache if on shared computer

2. **Performance**:
   - Use specific base paths for searches
   - Adjust cache settings based on your usage
   - Increase cache expiration if secrets change rarely
   - Decrease for frequently updated secrets

3. **Organization**:
   - Name servers clearly
   - Add descriptions to help identify servers
   - Use consistent path naming in Vault
   - Structure secrets logically

4. **Maintenance**:
   - Periodically clear cache
   - Review cache statistics
   - Adjust settings as usage patterns change
   - Remove unused vault server configurations

## Keyboard Shortcuts

- **Enter** in Secret Path field: Read the secret
- **Enter** in Search Term field: Start search
- **Esc** in Settings modal: Close settings

## Data Storage

### What's Stored in localStorage:
- ✅ Vault server configurations (name, URL, description)
- ✅ Application settings (cache size, search limits, etc.)
- ✅ Cached API responses (paths, secrets)

### What's NOT Stored:
- ❌ Vault tokens
- ❌ Passwords
- ❌ Any credentials

Credentials are only kept in memory during your active session and are lost when you logout or close the tab.