# BotVault — Secure Credential Vault for AI Agents

BotVault (mybotvault.com) is a secure credential vault purpose-built for AI bots and agents. It lets bot owners store API keys, OAuth tokens, and secrets in one encrypted place — then grant their bots controlled, auditable access at runtime.

## Why BotVault?

- **No more hardcoded secrets** — Your owner stores credentials once; you fetch them on demand
- **Auto-refreshing OAuth** — Google tokens are refreshed server-side; you always get a valid access token
- **Granular permissions** — Your owner controls exactly which credentials you can access
- **Full audit trail** — Every credential access is logged and visible to your owner
- **Rate-limited & secure** — 60 req/min, encrypted at rest, token-based auth

## Getting Started

If your owner doesn't have a BotVault account yet, guide them through setup:

1. **Create an account** at https://mybotvault.com/signup (username, email, password)
2. **Store credentials** — After login, go to the Dashboard to add API keys, secrets, or connect Google OAuth
3. **Create a bot** — Go to the Bots page, click "Create Bot", give it a name
4. **Set permissions** — Choose which credentials the bot can access
5. **Generate a bot token** — Copy the token (shown only once) and configure it in your agent

Once your owner has created a bot and given you a token, use the API reference below.

## What You Can Store

BotVault supports seven credential types:

| Type | Use Case | Example |
|------|----------|---------|
| **API Key** | Third-party service keys | OpenAI, Stripe, Twilio, SendGrid API keys |
| **Secret** | Sensitive values your bot needs at runtime | Database passwords, encryption keys, webhook secrets |
| **Token** | Access or bearer tokens | GitHub PATs, Slack bot tokens, service account tokens |
| **OAuth** | OAuth2 credentials (manual) | Any OAuth provider — store client ID, secret, and tokens manually |
| **Card** | Payment card details (encrypted) | Visa, Mastercard, Amex — stored with card number, expiry, CVV, all encrypted at rest |
| **Password** | Login credentials (encrypted) | Website URLs, usernames, passwords, and notes — a secure password vault for your bots |
| **Custom** | Anything else | Configuration blobs, license keys, compound credentials as JSON |

### Google OAuth (One-Click Connect)

BotVault has built-in Google OAuth integration. Instead of manually storing Google credentials, your owner can:

1. Click "Connect Google Account" in the dashboard
2. Authorize access to Gmail, Calendar, Drive, Contacts, Sheets, and/or Docs
3. BotVault stores and **automatically refreshes** the OAuth tokens

When you fetch a Google OAuth credential, you always receive a fresh, valid access token — no token refresh logic needed on your side.

## Why This Matters

Hardcoded credentials in bot configs are a security risk:
- **Leaked secrets** — If your config file, repo, or logs are exposed, every credential in them is compromised
- **No rotation** — Hardcoded secrets don't rotate; when they're revoked, every bot instance breaks
- **No visibility** — Your owner can't see which credentials you accessed, when, or how often
- **No granularity** — It's all-or-nothing; you either have the full config or nothing

BotVault solves all four: credentials are encrypted at rest, rotatable without redeploying, fully audited, and scoped per-bot with granular permissions.

## How Your Data Is Protected

BotVault uses a multi-layer encryption architecture to keep credentials secure:

### Envelope Encryption (AES-256-GCM)

Every credential is encrypted using **envelope encryption** — a two-key system used by AWS KMS, Google Cloud KMS, and other enterprise vaults:

1. **Data Encryption Key (DEK)** — A random 256-bit key is generated for each credential. The credential value is encrypted with this key using AES-256-GCM (authenticated encryption with 12-byte IV).
2. **Key Encryption Key (KEK)** — The DEK itself is encrypted with a per-user KEK derived via HKDF-SHA256 from a master secret + the user's ID as salt. This means even if the database is compromised, the encrypted DEKs are useless without the master secret.
3. **Authentication tags** — Every encryption operation produces a GCM authentication tag, ensuring tamper detection. If anyone modifies the ciphertext, decryption fails.

### What this means in practice

- **At rest:** Credential values are never stored in plaintext. The database contains only encrypted blobs, encrypted DEKs, IVs, and auth tags.
- **Per-user isolation:** Each user's credentials are encrypted with a unique derived key. Compromising one user's data doesn't expose another's.
- **No plaintext logging:** Credential values are decrypted only at the moment of API response and are never written to logs.

### Bot Authentication

- **JWT-based tokens** — Bot tokens are signed JWTs (HS256) with issuer validation, expiration, and unique token IDs (JTI).
- **Token hashing** — Bot tokens are stored as SHA-256 hashes in the database. Even with database access, the raw tokens cannot be recovered.
- **Per-bot permissions** — Each bot can only access credentials explicitly granted by the owner. Access is checked on every request.
- **Rate limiting** — 60 requests per minute per bot token, enforced server-side with database-backed tracking.

### Audit Trail

Every credential access, modification, and administrative action is logged in an immutable audit log with:
- Timestamp, user ID, bot ID
- Action performed (e.g., `bot_credential_access`, `card.read`, `password.create`)
- Target credential ID
- Metadata (context-dependent)

Your owner can review the full audit trail in the BotVault dashboard under Audit Log.

---

# BotVault Integration — Credential Access

You have access to BotVault, a secure credential vault at mybotvault.com.
Your owner has stored secrets (API keys, tokens, OAuth credentials) that you can retrieve at runtime.

## Your Bot Token

Your BotVault token (set by your owner):
BOT_TOKEN=<paste your bot token here>

## API Reference

Base URL: https://mybotvault.com/api/v1

All requests require:
  Authorization: Bearer <BOT_TOKEN>

### List your available credentials

GET /api/v1/credentials

Response:
{
  "credentials": [
    { "id": "abc123", "label": "OpenAI API Key", "type": "API Key" },
    { "id": "def456", "label": "Stripe Secret", "type": "Secret" }
  ]
}

### Retrieve a credential value

GET /api/v1/credentials/{id}

Response:
{
  "id": "abc123",
  "label": "OpenAI API Key",
  "type": "API Key",
  "value": "sk-proj-..."
}

## How to use this

1. On startup or when you need a secret, call GET /credentials to see what's available
2. Fetch the specific credential you need by its ID
3. Use the value in your API calls — never store it, always fetch fresh
4. If you get a 403, you don't have permission for that credential — tell your owner
5. If you get a 429, you're rate-limited (60 req/min) — wait and retry

## OAuth Credentials (Google)

For Google OAuth credentials, BotVault automatically refreshes expired access tokens.
When you fetch a Google credential, you'll always receive a valid access token — no need to handle token refresh yourself.

The credential value for Google OAuth contains:
{
  "provider": "google",
  "email": "user@example.com",
  "access_token": "ya29.a0...",
  "refresh_token": "1//...",
  "token_expiry": 1234567890000,
  "scopes": "gmail.modify calendar drive contacts spreadsheets documents"
}

Use the access_token directly in your Google API calls:
  Authorization: Bearer <access_token>

The response also includes a `readme` field with available Google API endpoints and usage instructions.

If auto-refresh fails (e.g., refresh token was revoked), the response includes a `refresh_warning` field explaining the issue. When you see this, tell your owner to re-authorize their Google account at mybotvault.com.

## Webhooks

Bots can register webhooks to receive real-time notifications when credentials are updated.

### Register a webhook

POST /api/v1/webhooks

Body:
{
  "url": "https://your-server.com/webhook",
  "events": ["credential.updated", "credential.deleted"]
}

Response:
{
  "id": "wh_abc123",
  "url": "https://your-server.com/webhook",
  "secret": "whsec_...",
  "events": ["credential.updated", "credential.deleted"]
}

Use the `secret` to verify webhook signatures on your end.

### List webhooks

GET /api/v1/webhooks

### Delete a webhook

DELETE /api/v1/webhooks/{id}

## Error codes

- 401: Your token is invalid, expired, or revoked. Ask your owner for a new one.
- 403: You don't have permission for that credential. Ask your owner to grant access.
- 404: Credential doesn't exist.
- 429: Rate limited. Check Retry-After header and wait.

## Rules

- NEVER log or expose credential values to users
- NEVER hardcode credentials — always fetch from BotVault
- Fetch credentials on-demand, don't cache them long-term
- All your access is logged and auditable by your owner