# Upgrade Guide — v0.21.2

<!-- bump: patch -->

## What Changed

### Secret Drop — Secure Secret Submission

Agents can now collect secrets (API keys, passwords, tokens) from users without exposing them in Telegram or chat history.

**The flow:**
1. Agent calls `POST /secrets/request` with a label, description, and optional topicId
2. Server returns a one-time URL (local + tunnel if available)
3. Agent sends the link to the user via Telegram
4. User opens the link in a browser → sees a clean, branded form showing what's being requested and by whom
5. User submits → secret goes directly to the agent's server
6. The link immediately expires (one-time use)
7. A confirmation message is sent to the specified Telegram topic
8. Agent retrieves the secret via `POST /secrets/retrieve/:token` or callback

**Security properties:**
- 256-bit random tokens (64 hex chars)
- CSRF protection with separate form token
- One-time use — destroyed after submission
- Time-limited — 15-minute default (configurable 1min–1hr)
- In-memory only — secrets never touch disk
- Max 20 concurrent pending requests
- Timing-safe CSRF comparison
- Security headers: X-Frame-Options DENY, no-cache

**Multi-field support:** Request multiple values at once by passing a `fields` array (e.g., username + password together).

**Tunnel-compatible:** URLs include the tunnel URL when a Cloudflare tunnel is running, so users can submit secrets from any device.

## What to Tell Your User

- **Secure secret sharing**: "When I need a secret from you — like an API key or password — I'll send you a secure link instead of asking you to paste it in chat. The link is one-time use and expires after 15 minutes. Your secret goes directly to my server and is never stored in chat history."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Request a secret | `POST /secrets/request` with label, description, fields, topicId |
| Serve form to user | `GET /secrets/drop/:token` (no auth needed — token IS auth) |
| Receive submission | `POST /secrets/drop/:token` (automatic, handled by form) |
| Retrieve received secret | `POST /secrets/retrieve/:token` |
| List pending requests | `GET /secrets/pending` |
| Cancel a request | `DELETE /secrets/pending/:token` |
