browser-vault-gui/README.md

# Browser Vault GUI

A modern Vue 3 + TypeScript frontend for HashiCorp Vault with Tailwind CSS and DaisyUI. This is an alternative web interface that allows you to connect to multiple Vault servers and manage your secrets.

## Features

- 🔐 **Multiple Vault Servers**: Add and manage connections to multiple Vault instances
- 🔑 **Multiple Auth Methods**: Support for Token, Username/Password, and LDAP authentication
- 🔍 **Recursive Path Search**: Search through vault paths recursively with configurable depth limits
- 💾 **Smart Caching**: API responses are cached in localStorage to prevent DDoS and reduce server load
- ⚙️ **Configurable Settings**: Adjust cache size, expiration time, search depth, and result limits
- 📊 **Cache Statistics**: Monitor cache usage with real-time statistics
- 🎨 **Modern UI**: Beautiful, responsive interface with dark/light mode support (Tailwind + DaisyUI)
- 🚀 **Fast**: Built with Vite for lightning-fast development and builds
- 🔒 **Secure by Default**: Credentials stored in memory only (optional localStorage with warnings)

## Getting Started

### Prerequisites

- Node.js 18+ and npm (or yarn/pnpm)

### Installation

1. Install dependencies:
```bash
npm install
```

2. Start the development server:
```bash
npm run dev
```

3. Open your browser and navigate to `http://localhost:5173`

### Building for Production

```bash
npm run build
```

The built files will be in the `dist/` directory.

## Usage

1. **Add a Vault Server**:
   - Click "Add Server" button
   - Enter server name, URL, and optional description
   - Click "Add Server" to save

2. **Connect to a Server**:
   - Select a server from the list
   - Choose your authentication method
   - Enter your credentials
   - Click "Connect"

3. **Browse and Search Secrets**:
   - Once connected, use the secret browser to read secrets
   - Enter the path to your secret (e.g., `secret/data/myapp/config`)
   - Click "Read Secret" or press Enter
   - Or use the "🔍 Search" button to recursively search for paths
   - Search results are cached automatically

4. **Configure Settings**:
   - Click "⚙️ Settings" to adjust cache and search parameters
   - Set maximum cache size (in MB)
   - Configure cache expiration time
   - Adjust maximum search depth and result limits
   - View cache statistics and clear cache if needed

## Implementation Notes

This application includes a **working Vault API client** with the following features:

✅ **Implemented:**
- Read secrets from Vault
- List secrets at a given path
- Recursive path search with caching
- Configurable cache system
- Settings management

🚧 **To be implemented:**
- Write/update secrets
- Delete secrets
- Policy management
- Audit log viewing
- Authentication flows (currently requires pre-existing token/credentials)

### CORS Configuration

To use this with your Vault server, you'll need to configure CORS. Add the following to your Vault server configuration:

```hcl
ui = true

listener "tcp" {
  address = "0.0.0.0:8200"
  tls_disable = 1
  
  cors_enabled = true
  cors_allowed_origins = ["http://localhost:5173", "https://yourdomain.com"]
  cors_allowed_headers = ["*"]
}
```

### Vault API Endpoints

The Vault HTTP API endpoints you'll need to implement:

- **Authentication**: `POST /v1/auth/<method>/login`
- **Read Secret**: `GET /v1/<path>`
- **Write Secret**: `POST /v1/<path>`
- **Delete Secret**: `DELETE /v1/<path>`
- **List Secrets**: `LIST /v1/<path>` (or `GET /v1/<path>?list=true`)

Remember to include the `X-Vault-Token` header with your authentication token for all authenticated requests.

## Security Considerations

⚠️ **Important Security Notes**:

- This application stores Vault server URLs and cached API responses in localStorage
- **Credentials are NOT persisted by default** - they are only kept in memory during the active session
- Cached responses may contain sensitive secret paths and secret data
- Always use HTTPS URLs for production Vault servers
- Be aware of CORS restrictions when connecting to Vault servers

### ⚠️ Optional Credential Saving (NOT RECOMMENDED)

The app includes an **optional** feature to save credentials locally:

- **Default**: Credentials are NEVER saved ✅ (Recommended)
- **Optional**: Users can choose to save credentials with explicit warnings ⚠️

**If you enable credential saving:**
- A prominent security warning is shown before saving
- Credentials are stored in **plain text** in localStorage
- Anyone with access to your browser can read them
- This violates most security policies
- **Only use for personal development/testing**

See `SECURITY_CREDENTIALS.md` for detailed security analysis.

### Cache Security

The cache stores:
- ✅ Secret paths and directory listings (for search performance)
- ❌ **Secret data is NEVER cached** (always fetched fresh for security)
- ⚠️ Credentials (ONLY if user explicitly enables with warnings)

Cache can be cleared manually from Settings.

## Technology Stack

- **Vue 3** - Progressive JavaScript framework with Composition API
- **TypeScript** - Type safety throughout
- **Tailwind CSS** - Utility-first CSS framework
- **DaisyUI** - Beautiful component library for Tailwind
- **Vite** - Lightning-fast build tool and dev server
- **Custom Vault Client** - Browser-compatible Vault HTTP API client with retries, timeouts, and error handling

## Development

### Project Structure

```
src/
├── components/         # Vue 3 components
│   ├── ServerSelector.vue
│   ├── LoginForm.vue
│   ├── Dashboard.vue
│   ├── PathSearch.vue
│   └── Settings.vue
├── services/
│   ├── vaultClient.ts # Low-level Vault HTTP API client
│   └── vaultApi.ts    # High-level API with caching
├── utils/
│   └── cache.ts       # Cache management system
├── types.ts           # TypeScript type definitions
├── config.ts          # Application configuration
├── App.vue            # Main application component
├── main.ts            # Application entry point
└── style.css          # Tailwind CSS imports
```

### Scripts

- `npm run dev` - Start development server (Vite)
- `npm run build` - Build for production (Vue TSC + Vite)
- `npm run preview` - Preview production build
- `npm run lint` - Run ESLint (Vue + TypeScript)

### Migration Note

This project was recently migrated from React to Vue 3. See `VUE_MIGRATION.md` for details.

## License

This project is open source and available under the MIT License.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.