browser-vault-gui/README.md

# Browser Vault GUI

A modern TypeScript/React frontend for HashiCorp Vault. 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
- 🚀 **Fast**: Built with Vite for lightning-fast development and builds
- 🔒 **Secure**: Credentials are only stored in memory, never persisted

## 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 NEVER persisted** - they are only kept in memory during the active session
- Cached responses may contain sensitive secret paths (but not the secret values themselves)
- Always use HTTPS URLs for production Vault servers
- Consider implementing additional security measures for production use:
  - Implement token refresh mechanisms
  - Add session timeout
  - Clear cache on logout
  - Use secure token storage (e.g., sessionStorage instead of memory for shorter sessions)
- Be aware of CORS restrictions when connecting to Vault servers

### Cache Security

The cache stores:
- ✅ Secret paths and directory listings
- ✅ Secret data (encrypted at rest by browser's localStorage encryption, if available)
- ❌ Credentials (never cached)

Cache can be cleared manually from Settings or programmatically on logout.

## Technology Stack

- **React 18** - UI framework
- **TypeScript** - Type safety
- **Vite** - Build tool and dev server
- **CSS3** - Styling with CSS custom properties
- **Custom Vault Client** - Browser-compatible Vault HTTP API client with retries, timeouts, and error handling

## Development

### Project Structure

```
src/
├── components/         # React components
│   ├── ServerSelector.tsx/css
│   ├── LoginForm.tsx/css
│   ├── Dashboard.tsx/css
│   ├── PathSearch.tsx/css
│   └── Settings.tsx/css
├── 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.tsx/css        # Main application component
├── main.tsx           # Application entry point
└── index.css          # Global styles
```

### Scripts

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run preview` - Preview production build
- `npm run lint` - Run ESLint

## License

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

## Contributing

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