auramaxx 1.0.0-alpha.4

package/docs/AUTH.md

@@ -0,0 +1,698 @@
+# Authentication & Permissions
+
+This document describes the authentication system and permission model for AuraWallet.
+
+## For Agents
+
+> **IMPORTANT**: If you're an agent, request a token via `POST /auth` and wait for human approval. You do NOT need an admin token - those are only for emergency/headless scenarios where a human is completely out of the loop.
+
+```bash
+# 1. Request access (returns requestId + secret)
+curl -X POST http://localhost:4242/auth \
+  -H "Content-Type: application/json" \
+  -d '{"agentId": "my-agent", "permissions": ["wallet:create:hot", "send:hot", "fund"]}'
+
+# 2. Human approves in dashboard UI
+
+# 3. Poll for your token
+curl "http://localhost:4242/auth/<requestId>?secret=<secret>"
+```
+
+---
+
+## Auth Flow Comparison
+
+AuraWallet has multiple token flows for different scenarios. Use this table to pick the right one:
+
+| Flow | Endpoint | Who Uses It | Approval | Token TTL | Use Case |
+|------|----------|-------------|----------|-----------|----------|
+| **Agent Request** | `POST /auth` | AI agents | Human approval required | Custom (default 1h) | Standard agent onboarding — agent requests access, human approves |
+| **Human Unlock** | `POST /unlock` | Humans | Password (RSA-encrypted) + `pubkey` | 7 days | Unlock vault, get admin token for dashboard/API |
+| **Direct Create** | `POST /actions/token` | Admins | Admin auth + `pubkey` | Custom | Emergency/headless — skip approval flow entirely |
+| **Permission Upgrade** | `POST /auth/request-permissions` | Agents with token | Human approval required | Same as new token | Agent needs more permissions or wallet access |
+| **Human Action** | `POST /actions` | Agents with `action:create` | Human approval required | Custom (default 60s) | Per-operation approval — scoped temp token for one action. Server generates verified summary from actual action params |
+
+### Which flow should I use?
+
+- **I'm an AI agent connecting for the first time** → `POST /auth` (standard flow)
+- **I'm a human unlocking the wallet** → `POST /unlock` (returns admin token)
+- **I'm an agent and need to do something outside my permissions** → `POST /actions` (request approval for one action)
+- **I'm an agent and need permanent permission upgrades** → `POST /auth/request-permissions`
+- **I'm running a script/CI with no human** → `POST /actions/token` (requires admin token)
+
+### Token properties by flow
+
+| Property | Agent Request | Human Unlock | Direct Create | Permission Upgrade | Human Action |
+|----------|:---:|:---:|:---:|:---:|:---:|
+| Spending limits | Yes | No | Yes | Yes | Yes |
+| Wallet access grants | Yes | All | Yes | Yes | Yes |
+| Survives restart | No | No | No | No | No |
+| Revocable | Yes | Yes | Yes | Yes | Yes |
+| Requires human | Yes | Self (password) | No (admin) | Yes | Yes |
+
+---
+
+## Overview
+
+AuraWallet uses Bearer token authentication. Tokens are issued to agents after human approval and contain embedded permissions and spending limits.
+
+**Key Security Properties:**
+- Tokens are HMAC-signed with an in-memory `SIGNING_KEY`
+- Server restart invalidates ALL tokens (new SIGNING_KEY generated)
+- Spending limits are embedded in tokens and tracked in memory
+- Admin tokens bypass all permission checks
+
+---
+
+## Token Types
+
+### Agent Token
+
+Issued to AI agents after human approval. Contains specific permissions and limits.
+
+```typescript
+interface AgentTokenPayload {
+  agentId: string;           // Identifier for the agent
+  permissions: string[];     // Permission strings (see below)
+  exp: number;               // Expiration timestamp (ms)
+
+  // Per-permission limits (optional)
+  // Plain number = legacy single-currency limit (ETH)
+  // Record<string, number> = per-currency limits keyed by native token address
+  limits?: {
+    fund?: number | Record<string, number>;  // Limit for cold→hot transfers
+    send?: number | Record<string, number>;  // Limit for sends (optional)
+    swap?: number | Record<string, number>;  // Volume limit for swaps (optional)
+  };
+
+  // Wallet access grants
+  walletAccess?: string[];   // Additional wallet addresses this token can access
+}
+```
+
+### Admin Token
+
+Admin tokens are regular agent tokens with `admin:*` permission. Generated when wallet is unlocked via `POST /unlock`.
+
+```typescript
+// Admin token is just an AgentTokenPayload with:
+{
+  agentId: 'admin',
+  permissions: ['admin:*'],
+  exp: <7 days from creation>,
+  // ... no limits (admin has full access)
+}
+```
+
+**Key behaviors:**
+- Multiple admin tokens can exist simultaneously (each unlock creates a new one)
+- Admin tokens are revocable via `POST /actions/tokens/revoke`
+- Locking the wallet does NOT auto-revoke tokens (but most admin ops require unlocked wallet)
+- Server restart invalidates all tokens (including admin)
+
+---
+
+## Permissions Reference
+
+### Wallet Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `wallet:list` | List and view wallets | `GET /wallets`, `GET /wallets/transactions`, `GET /wallet/:address` |
+| `wallet:create:hot` | Create hot wallets | `POST /wallet/create` (tier: hot) |
+| `wallet:create:temp` | Create temp wallets | `POST /wallet/create` (tier: temp) |
+| `wallet:rename` | Update wallet metadata | `POST /wallet/rename` |
+| `wallet:export` | Export private keys | `POST /wallet/:address/export` |
+| `wallet:tx:add` | Add manual transaction records | `POST /wallet/:address/transactions` |
+| `wallet:asset:add` | Add tracked assets | `POST /wallet/:address/asset` |
+| `wallet:asset:remove` | Remove tracked assets | `DELETE /wallet/:address/asset/:id` |
+
+### Transaction Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `send:hot` | Send from hot wallets | `POST /send` (from hot wallet) |
+| `send:temp` | Send from temp wallets | `POST /send` (from temp wallet) |
+| `swap` | Execute token swaps | `POST /swap` |
+| `fund` | Transfer from cold to hot | `POST /fund` |
+| `launch` | Execute token launches via Doppler | `POST /launch` |
+
+### API Key Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `apikey:get` | Read API keys | `GET /apikeys` |
+| `apikey:set` | Create/update/delete API keys | `POST /apikeys`, `DELETE /apikeys/:id` |
+
+### Credential Vault Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `secret:read` | List credential metadata and read credential fields (encrypted to token pubkey) | `GET /credentials`, `GET /credentials/:id`, `POST /credentials/:id/read` |
+| `secret:write` | Create, update, and delete credentials | `POST /credentials`, `PUT /credentials/:id`, `DELETE /credentials/:id` |
+
+### Credential Access Controls
+
+Tokens with secret permissions can include `credentialAccess`:
+
+- `read` / `write`: scope arrays (`*`, `vault:<id>`, `tag:<name>`, or specific credential IDs)
+- `excludeFields`: remove sensitive field keys from read responses
+- `ttl`: credential-read lifetime in seconds from token `iat`
+- `maxReads`: maximum successful credential reads for the token
+
+### Agent Profiles (Policy Packs)
+
+`POST /auth` and `POST /actions/token` support policy profile issuance:
+
+- `profile` (required for profile mode): profile id (`observer`, `deploy-bot`, `rotation-bot`, `trader`)
+- `profileVersion` (optional, default `v1`)
+- `profileOverrides` (optional tighten-only constraints)
+
+When `profile` is provided, profile policy becomes the source of truth for:
+
+- `permissions`
+- `credentialAccess`
+- `ttl`
+
+Response metadata includes:
+
+- `profile`
+- `effectivePolicyHash`
+- `overrideDelta`
+- `warnings`
+
+#### Override constraints (fail-closed)
+
+Profile overrides are **tighten-only**:
+
+- `ttlSeconds`: must be positive and <= profile default
+- `maxReads`: must be positive and <= profile default
+- `readScopes` / `writeScopes`: must be subsets of profile scopes (no broadening)
+- `excludeFields`: cannot remove profile-required exclusions (can only add)
+
+Invalid profile ids/versions or unsafe overrides return stable profile error codes (for deterministic automation handling).
+
+### Mandatory `pubkey` on Token Minting
+
+All token mint paths require a valid RSA public key (`pubkey` / `requestedPubkey`):
+
+- `POST /unlock`
+- `POST /unlock/:vaultId`
+- `POST /setup`
+- `POST /auth`
+- `POST /actions/token`
+- token-issuing approval flows (`POST /actions`, `POST /actions/:id/resolve`, `POST /auth/request-permissions`)
+
+The server normalizes and stores this value on the token as `agentPubkey`. Credential reads (`POST /credentials/:id/read`) are encrypted to that key and never returned in plaintext.
+
+### Strategy Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `strategy:read` | View strategies and their state | `GET /strategies`, `GET /strategies/:id/config`, `GET /strategies/:id/state`, `GET /strategies/history` |
+| `strategy:manage` | Enable/disable strategies, update config, approve intents/apps | `POST /strategies/:id/toggle`, `PUT /strategies/:id/config`, `POST /strategies/:id/approve`, `POST /strategies/reload`, `POST /apps/:id/approve`, `DELETE /apps/:id/approve` |
+
+### App Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `app:storage` | Read/write own app's storage and send messages (scoped by agentId). Auto-granted to all app tokens. | `GET /apps/:id/storage`, `GET /apps/:id/storage/:key`, `PUT /apps/:id/storage/:key`, `DELETE /apps/:id/storage/:key`, `POST /apps/:id/message` |
+| `app:storage:all` | Read/write ANY app's storage (cross-app) | Same routes as `app:storage`, bypasses scope check |
+| `app:accesskey` | Read API keys from app storage. Auto-granted to app tokens whose sources use `key` fields. | `GET /apps/:id/apikey/:keyName` |
+
+**App token agentId prefixes:** App tokens use `app:<appId>` as their agentId (e.g., `app:tic-tac-toe`). Legacy strategy tokens use `strategy:<appId>`. The storage scope enforcement strips both prefixes when matching against the URL's `:appId` parameter.
+
+### Address Book & Bookmark Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `addressbook:write` | Create, update, and delete address labels | `POST /address-labels`, `DELETE /address-labels/:id` |
+| `bookmark:write` | Create and delete token bookmarks (watchlist) | `POST /bookmarks`, `DELETE /bookmarks/:id` |
+
+### Action Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `action:create` | Create human action requests (propose actions for approval), send notifications, and enable `request_human_action` tool in chat apps | `POST /actions` |
+
+**Verified summaries:** When an agent creates an action request via `POST /actions`, the server generates a `verifiedSummary` from the actual pre-computed action parameters (endpoint, body, amounts, recipients). This is stored in the action metadata alongside the agent's `summary` text. The dashboard shows the server-generated one-liner and flags discrepancies (e.g., agent says "Swap 0.01 ETH" but the action body contains 10 ETH). Summary text is limited to 500 characters.
+
+### Compound Permissions
+
+Compound permissions expand to multiple underlying permissions for convenience.
+
+| Permission | Description | Expands To |
+|------------|-------------|------------|
+| `trade:all` | All trading permissions | `wallet:list`, `wallet:create:hot`, `wallet:create:temp`, `send:hot`, `send:temp`, `swap`, `fund`, `launch`, `apikey:get`, `strategy:read` |
+| `wallet:write` | All wallet write operations | `wallet:create:hot`, `wallet:create:temp`, `wallet:rename`, `wallet:tx:add`, `wallet:asset:add`, `wallet:asset:remove` |
+
+**Usage Example:**
+```typescript
+// Instead of listing all trading permissions:
+permissions: ['wallet:list', 'wallet:create:hot', 'send:hot', 'swap', 'fund', 'apikey:get']
+
+// Use the compound permission:
+permissions: ['trade:all']
+```
+
+**Onboarding note:** `trade:all` does NOT include `apikey:set` or `adapter:manage`. Agents helping with first-time setup (configuring API keys, Telegram adapter) should request these explicitly:
+```typescript
+permissions: ['trade:all', 'apikey:set', 'adapter:manage', 'action:create']
+```
+See the [SKILL.md](../skills/aurawallet/SKILL.md) agent reference for the full onboarding guide.
+
+### UI/Workspace Operations
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `workspace:modify` | Modify dashboard workspaces | WebSocket events (app:added, etc.) |
+
+### Admin
+
+| Permission | Description | Routes |
+|------------|-------------|--------|
+| `admin:*` | Full access, bypass all checks | All routes |
+
+---
+
+## Route → Permission Mapping
+
+| Route | Method | Permission Required | Notes |
+|-------|--------|---------------------|-------|
+| `/wallets` | GET | *public* | No auth required |
+| `/wallet/:address` | GET | `wallet:list` | Optional auth, agents see only owned |
+| `/wallet/create` | POST | `wallet:create:hot` or `wallet:create:temp` | Based on tier |
+| `/wallet/rename` | POST | `wallet:rename` | + wallet access |
+| `/wallet/:address/export` | POST | `wallet:export` | + wallet access + unlocked |
+| `/wallets/transactions` | GET | `wallet:list` | Optional auth, agents see only owned |
+| `/wallet/:address/transactions` | GET | `wallet:list` | Optional auth for own wallets; no auth for external addresses (on-chain fallback) |
+| `/wallet/:address/transactions` | POST | `wallet:tx:add` | + wallet access |
+| `/wallet/:address/assets` | GET | `wallet:list` | Optional auth, agents see only owned |
+| `/wallet/:address/asset` | POST | `wallet:asset:add` | + wallet access |
+| `/wallet/:address/asset/:id` | DELETE | `wallet:asset:remove` | + wallet access |
+| `/send` | POST | `send:hot` or `send:temp` | Based on wallet tier |
+| `/swap` | POST | `swap` | + wallet access |
+| `/fund` | POST | `fund` | Limit enforced |
+| `/launch` | POST | `launch` | + wallet access |
+| `/launch/collect-fees` | POST | *(any token)* | Permissionless on-chain; wallet access for gas |
+| `/launch/:addr/collect-fees` | POST | *(any token)* | Permissionless on-chain; wallet access for gas |
+| `/auth/connect` | GET | *public* | Get server public key for password encryption |
+| `/auth` | POST | *public* | Request token (`pubkey` required) |
+| `/auth/:id` | GET | *public* | Poll for token |
+| `/auth/validate` | POST | *any valid token* | Validate token |
+| `/apikeys` | GET | `apikey:get` or `trade:all` | List all API keys |
+| `/apikeys` | POST | `apikey:set` | Create/update API key |
+| `/apikeys/validate` | POST | `apikey:set` | Validate API key against external service |
+| `/apikeys/:id` | DELETE | `apikey:set` | Delete API key |
+| `/unlock` | GET | *public* | Self-contained HTML unlock page (browser-based) |
+| `/unlock` | POST | *public* | Unlock primary vault and mint admin token (`pubkey` required) |
+| `/unlock/:vaultId` | POST | *public* | Unlock specific vault and mint admin token (`pubkey` required) |
+| `/lock` | POST | `admin:*` | Locks ALL vaults. Admin only |
+| `/lock/:vaultId` | POST | `admin:*` | Lock a specific vault. Admin only |
+| `/vaults/credential` | GET | `admin:*` | List credential vaults |
+| `/vaults/credential` | POST | `admin:*` | Create credential vault |
+| `/vaults/credential/:id/lock` | POST | `admin:*` | Lock credential vault |
+| `/vaults/credential/:id` | DELETE | `admin:*` | Delete credential vault + credentials |
+| `/credentials` | GET | `secret:read` or `admin:*` | List credential metadata (scope filtered) |
+| `/credentials` | POST | `secret:write` or `admin:*` | Create credential |
+| `/credentials/:id` | GET | `secret:read` or `admin:*` | Get credential metadata |
+| `/credentials/:id` | PUT | `secret:write` or `admin:*` | Update credential |
+| `/credentials/:id` | DELETE | `secret:write` or `admin:*` | Delete credential |
+| `/credentials/:id/read` | POST | `secret:read` or `admin:*` | Read credential (encrypted to `agentPubkey`) |
+| `/setup/vault` | POST | `admin:*` | Create additional vault. Requires unlocked primary |
+| `/setup/vault/import` | POST | `admin:*` | Import vault from seed. Requires unlocked primary |
+| `/setup/vaults` | GET | *public* | List all vaults and their status |
+| `/export-seed` | GET/POST | `admin:*` | Export seed phrase. Optional `vaultId` param |
+| `/actions` | POST | `action:create` | Create human action request |
+| `/actions/token` | POST | `admin:*` | Direct token creation (`pubkey` required) |
+| `/actions/:id/resolve` | POST | `admin:*` | Approve/reject pending action |
+| `/actions/tokens` | GET | `admin:*` | List all tokens |
+| `/actions/tokens/revoke` | POST | `admin:*` or own token | Revoke a token |
+| `/nuke` | POST | `admin:*` | Admin only |
+| `/defaults` | GET | `admin:*` | List all system defaults |
+| `/defaults/:key` | PATCH | `admin:*` | Update a system default |
+| `/defaults/reset` | POST | `admin:*` | Reset system default(s) to seed values |
+| `/ai/status` | GET | `admin:*` | AI provider status and availability |
+| `/adapters` | GET | `adapter:manage` | List configured adapters |
+| `/adapters` | POST | `adapter:manage` | Add/update adapter config |
+| `/adapters/:type` | DELETE | `adapter:manage` | Remove adapter config |
+| `/adapters/test` | POST | `adapter:manage` | Send test message through adapter |
+| `/adapters/restart` | POST | `adapter:manage` | Restart approval router |
+| `/address-labels` | GET | *any token or admin* | List all address labels |
+| `/address-labels` | POST | `addressbook:write` | Create/update address label |
+| `/address-labels/:id` | DELETE | `addressbook:write` | Delete address label |
+| `/bookmarks` | GET | *any token or admin* | List bookmarked tokens |
+| `/bookmarks` | POST | `bookmark:write` | Create token bookmark |
+| `/bookmarks/:id` | DELETE | `bookmark:write` | Delete bookmark |
+| `/health` | GET | *public* | No auth required |
+| `/price/:address` | GET | *public* | Token price lookup |
+| `/token/search` | GET | *public* | Search tokens by ticker/name |
+| `/token/safety/:address` | GET | *public* | Token safety report (GoPlusLabs) |
+| `/token/holders/:address` | GET | *public* | Top holders for a token |
+| `/token/:tokenAddress/balance/:walletAddress` | GET | *public* | On-chain token balance for any address |
+| `/batch` | POST | *public* | Batch multiple API calls with dependency chaining (auth per-sub-request) |
+| `/strategies` | GET | `strategy:read` | List all strategies |
+| `/strategies/:id/toggle` | POST | `strategy:manage` | Enable/disable strategy |
+| `/strategies/:id/config` | GET | `strategy:read` | Get effective config |
+| `/strategies/:id/config` | PUT | `strategy:manage` | Update config overrides |
+| `/strategies/:id/approve` | POST | `strategy:manage` | Approve/reject intents |
+| `/strategies/:id/state` | GET | `strategy:read` | Get strategy state (debug) |
+| `/strategies/history` | GET | `strategy:read` | Strategy action history |
+| `/strategies/reload` | POST | `strategy:manage` | Hot-reload from disk |
+| `/apps/:id/storage` | GET | `app:storage` | List all storage keys |
+| `/apps/:id/storage/:key` | GET | `app:storage` | Get storage value |
+| `/apps/:id/storage/:key` | PUT | `app:storage` | Set storage value |
+| `/apps/:id/storage/:key` | DELETE | `app:storage` | Delete storage key |
+| `/apps/:id/apikey/:keyName` | GET | `app:accesskey` | Get API key from app storage |
+| `/apps/:id/message` | POST | `app:storage` | Send message to app AI (scoped) |
+| `/apps/:id/reload` | POST | `admin:*` | Hot-reload app token after install |
+| `/apps/:id/approve` | POST | `strategy:manage` | Approve app permissions |
+| `/apps/:id/approve` | DELETE | `strategy:manage` | Revoke app approval |
+---
+
+## Token Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. Agent requests token                                         │
+│     POST /auth { agentId, permissions, limits, ttl, pubkey }    │
+│     → Returns requestId + secret                                 │
+├─────────────────────────────────────────────────────────────────┤
+│  2. Human approves via UI or API                                 │
+│     POST /actions/:id/resolve { approved: true }                 │
+│     → Token signed with SIGNING_KEY                              │
+├─────────────────────────────────────────────────────────────────┤
+│  3. Agent polls for token                                        │
+│     GET /auth/:requestId?secret=XXX                              │
+│     → Returns signed token                                       │
+├─────────────────────────────────────────────────────────────────┤
+│  4. Agent uses token                                             │
+│     Authorization: Bearer <token>                                │
+│     → Validated against SIGNING_KEY                              │
+│     → Spending tracked in memory                                 │
+├─────────────────────────────────────────────────────────────────┤
+│  5. Agent requests permission upgrade (optional)                   │
+│     POST /auth/request-permissions { requestedPermissions, requestedPubkey, ... } │
+│     → Creates permission_update pending request                   │
+│     → Human approves → poll for new token (same flow as step 3)  │
+├─────────────────────────────────────────────────────────────────┤
+│  6. Token invalidation                                           │
+│     - Server restart (new SIGNING_KEY) - ALL tokens invalid      │
+│     - Human revokes: POST /actions/tokens/revoke                 │
+│     - Token expires (exp timestamp)                              │
+│     NOTE: Locking wallet does NOT invalidate tokens              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## External Approval Channels
+
+In addition to the Dashboard UI and CLI terminal, approvals can flow through external channels (Telegram, Discord, webhooks) via the adapter system. All channels converge on the same `POST /actions/:id/resolve` endpoint.
+
+See [docs/ADAPTERS.md](./ADAPTERS.md) for configuration, built-in adapters, and how to build custom adapters.
+
+---
+
+## Wallet Access Model
+
+Tokens can access wallets they own OR wallets explicitly granted via `walletAccess`:
+
+```typescript
+// Token can access wallet if:
+// 1. Token created the wallet (tokenHash matches), OR
+// 2. Wallet address is in token's walletAccess array
+
+function tokenCanAccessWallet(tokenHash, walletAccess, address): boolean
+```
+
+| Action | Who Can Do It |
+|--------|---------------|
+| Create hot wallet | Agent with `wallet:create:hot` permission |
+| Send from wallet | Token that owns it OR has it in `walletAccess` |
+| Export private key | Token owner OR admin with unlocked wallet |
+| List wallets | Token sees owned wallets, admin sees all |
+
+---
+
+## Spending Limits
+
+Limits are only enforced on `/fund` (cold→hot transfers):
+
+```typescript
+// Token has embedded limits
+{
+  limits: {
+    fund: 1.0,    // Max 1 ETH from cold wallet
+    send: null,   // No limit on sends (optional)
+    swap: null    // No limit on swaps (optional)
+  }
+}
+
+// Spending tracked in memory per token
+sessions.get(tokenHash) = {
+  token: AgentTokenPayload,
+  spent: 0,
+  spentByType: {
+    fund: 0.5,   // Already used 0.5 of 1.0 ETH fund limit
+    send: 0,
+    swap: 0
+  }
+}
+```
+
+**Key Points:**
+- `/fund` limit is the primary control (cold wallet access)
+- `/send` has NO limit by default - agents spend freely from their hot wallets
+- Limits are tamper-proof (embedded in HMAC-signed token)
+- Server restart resets all spending (new sessions Map)
+
+---
+
+## API Keys
+
+AuraWallet stores API keys as encrypted credential-vault entries (`type: "apikey"`). Legacy `ApiKey` DB rows are migrated/synced for compatibility, and `/apikeys` is served through the credential vault path.
+
+### Get All API Keys
+
+```bash
+curl http://localhost:4242/apikeys \
+  -H "Authorization: Bearer <token>"
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "apiKeys": [
+    {
+      "id": "...",
+      "service": "alchemy",
+      "name": "default",
+      "keyMasked": "abc1****3xyz",
+      "createdAt": "2026-02-03T..."
+    }
+  ]
+}
+```
+
+### Create/Update API Key
+
+```bash
+curl -X POST http://localhost:4242/apikeys \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"service": "alchemy", "name": "default", "key": "your-api-key"}'
+```
+
+Requires `apikey:set` permission.
+
+### Delete API Key
+
+```bash
+curl -X DELETE http://localhost:4242/apikeys/<id> \
+  -H "Authorization: Bearer <token>"
+```
+
+Requires `apikey:set` permission.
+
+### Validate API Key
+
+```bash
+curl -X POST http://localhost:4242/apikeys/validate \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"service": "alchemy", "key": "your-api-key"}'
+```
+
+Validates an API key against its external service before saving. Requires `apikey:set` permission.
+
+**Supported services:**
+- `alchemy` — Sends `eth_blockNumber` JSON-RPC call. Valid if response contains a block number.
+- `anthropic` — Sends minimal request to Messages API. 200 or 429 (rate-limited) = valid, 401 = invalid.
+- `adapter:telegram` — Calls Telegram Bot API `getMe`. Returns `{ valid: true, info: { botUsername } }` on success.
+
+All external calls have a 5-second timeout. Returns `{ valid: false, error: "Validation timed out" }` on timeout.
+
+### Test Adapter
+
+```bash
+curl -X POST http://localhost:4242/adapters/test \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "telegram"}'
+```
+
+Sends a test message through a configured adapter. Requires `adapter:manage` permission.
+
+**Supported types:**
+- `telegram` — Reads bot token and chat ID from DB, sends a test message via Telegram Bot API. Returns 404 if token or chat ID not configured.
+- `webhook` — Reads webhook URL from adapter config, POSTs `{ type: "test", data: {}, timestamp }`. Returns 404 if URL not configured.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+---
+
+## Authentication Header
+
+```http
+Authorization: Bearer <token>
+```
+
+Example:
+```bash
+curl http://localhost:4242/wallets \
+  -H "Authorization: Bearer eyJhZ2VudElkIjoibXktYm90IiwicGVybWlzc2..."
+```
+
+---
+
+## Error Responses
+
+| Error | HTTP Status | Meaning |
+|-------|-------------|---------|
+| `Authentication required` | 401 | No token provided |
+| `Invalid or expired token` | 401 | Bad signature or expired |
+| `Token has been revoked` | 401 | Human revoked the token |
+| `Insufficient permissions` | 403 | Token lacks required permission |
+| `Token does not have access to this wallet` | 403 | Not owner, not in walletAccess |
+| `Admin access required` | 403 | Route requires admin token |
+| `Amount exceeds remaining spending limit` | 403 | Fund limit exceeded |
+| `Cold wallet must be unlocked` | 401 | Need human to unlock first |
+
+---
+
+## Encrypted Password Transport
+
+Passwords for `/unlock` and `/setup` are encrypted before transmission using RSA-OAEP. This protects against local interception by malware or other processes.
+
+### Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Server startup                                                  │
+│    → Generate ephemeral RSA keypair (private key in memory)     │
+├─────────────────────────────────────────────────────────────────┤
+│  Frontend unlock/setup                                           │
+│    1. GET /auth/connect → { publicKey: "-----BEGIN PUBLIC..." } │
+│    2. Encrypt password with RSA-OAEP using Web Crypto API       │
+│    3. Generate caller RSA keypair (local)                        │
+│    4. POST /unlock → { encrypted: "base64...", pubkey: "..." }  │
+├─────────────────────────────────────────────────────────────────┤
+│  Server                                                          │
+│    1. Decrypt with private key → plaintext password             │
+│    2. Normal unlock/setup flow                                  │
+│    3. Return result (admin token on unlock)                     │
+├─────────────────────────────────────────────────────────────────┤
+│  Server restart                                                  │
+│    → New RSA keypair generated                                  │
+│    → Old cached public keys become invalid                      │
+│    → Frontend auto-refetches on decryption failure              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+The server also provides a built-in unlock page at `GET /unlock` that handles the encryption flow automatically in the browser — no frontend build required. **This is a fallback for headless environments.** When the dashboard (`http://localhost:4747/app`) is available, prefer directing users there instead.
+
+### Security Properties
+
+- RSA private key never leaves server memory
+- Keypair regenerates on restart (aligns with existing security model)
+- RSA-OAEP provides semantic security (same plaintext → different ciphertext)
+- Passwords never appear in plaintext over HTTP
+
+### Usage (Frontend)
+
+```typescript
+import { unlockWallet, setupWallet } from '@/lib/api';
+
+// These functions handle encryption automatically
+const result = await unlockWallet(password);
+const result = await setupWallet(password);
+```
+
+---
+
+## Security Best Practices
+
+1. **Never expose ports to internet** - This is a local-only system
+2. **Store secrets securely** - The `secret` from `/auth` is needed to retrieve tokens
+3. **Use minimal permissions** - Request only the permissions you need
+4. **Handle token expiry** - Tokens expire, implement refresh logic
+5. **Expect restarts** - Server restart invalidates all tokens, this is intentional
+
+---
+
+## Note on Admin Tokens
+
+> **IMPORTANT**: 99% of the time you just need an agent token via `POST /auth`. If the wallet is unlocked, agents can request tokens through the normal human-approval flow. You should NOT need an admin token.
+
+Admin tokens are returned when unlocking the wallet via `/unlock`. In normal usage, **you should not need to use the admin token directly**. The dashboard UI handles authentication automatically.
+
+Admin tokens are intended for:
+- **Emergency access** - Recovering from UI issues or debugging
+- **Headless/automated scenarios** - When running without a human in the loop at all (e.g., CI/CD, scripts)
+- **API exploration** - Testing endpoints directly with curl
+
+For regular human-supervised operation:
+1. Just use the dashboard UI - it manages tokens internally
+2. Agents should request tokens via `POST /auth` and wait for human approval
+3. No admin token is needed for normal agent workflows
+
+---
+
+## Agent Permission Tiers
+
+The `agent-chat` app supports two permission tiers that control what the chat agent can do directly vs. what requires human approval.
+
+### Tiers
+
+| Tier | Permissions | Behavior |
+|------|-------------|----------|
+| **admin** (default) | `admin:*` | Agent can call `/send`, `/swap`, `/fund`, etc. directly. No approval popups. |
+| **restricted** | `wallet:list`, `action:create` | Agent can only view wallets and propose actions via `request_human_action`. All trades require human approval. |
+
+### Configuration
+
+The tier is stored as the system default `permissions.agent_tier`. It can be set:
+
+- **Dashboard Settings** → `DEFAULT_AGENT` section → Permission Tier toggle
+- **Setup Wizard** → AI Agent step → Permission Level toggle
+- **API**: `PATCH /defaults/permissions.agent_tier` with `{ "value": "admin" | "restricted" }`
+
+### How It Works
+
+1. When `createAppToken('agent-chat')` runs, it checks `permissions.agent_tier`
+2. If `admin` → the token gets `['admin:*']` permissions (full access)
+3. If `restricted` → the token keeps the app's declared permissions (`wallet:list`, `action:create`)
+4. Only the `agent-chat` app is affected — all other apps keep their own permissions
+
+### Token Refresh on Tier Change
+
+When `permissions.agent_tier` changes (via `PATCH /defaults`), the system automatically:
+1. Revokes the existing `agent-chat` app token
+2. Creates a new token with the updated permissions
+
+This happens via an `onDefaultChanged` listener, so the change takes effect immediately without server restart.