browser-vault-gui/USAGE.md

Usage Guide

Quick Start

1. Install and Run

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:

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.